POST /v1/products/lookup resolves one product page URL and returns a source-aware MerchantProductUrlLookupResponse. The default auto mode checks StoreRouter’s product index first, then uses on-demand product resolution if the URL is not indexed and that capability is available.
Request
Body parameters
Product page URL to resolve. The URL does not need to belong to a StoreRouter catalog unless
resolutionMode is index_only.Source selection policy.
auto checks the index and then resolves on demand after a miss. index_only never performs outbound work. on_demand_only skips the index. Allowed values: auto, index_only, on_demand_only.Cache behavior when the request can enter the on-demand path.
prefer_cache reuses a recent result when available. refresh requests a fresh resolution but does not bypass safety checks or rate limits. Allowed values: prefer_cache, refresh. This field does not apply to index_only.Example
Response
Request identifier for tracing an on-demand resolution. It may be
null for an indexed hit.Catalog source base URL for an indexed result.
null for an on-demand result or when not configured.Product detail view.
productUrl is always present. For on-demand results, uuid, catalogKey, and isActive are null; unsupported fields are null, omitted, or empty according to their existing schema defaults.Final URL after redirects. Populated for on-demand results when available;
use it for on-demand follow-up lookups.
The matched product’s URL as normalized by StoreRouter (HTTPS-forced,
www.
stripped, tracking parameters removed, query sorted). Populated for indexed
results. This is the stable URL: submit it on a follow-up lookup and it
deterministically re-resolves the same product. Prefer storing it over the
URL you originally submitted.The canonical URL the product page itself declares (JSON-LD
url,
og:url, or link rel="canonical"). Populated only for on-demand results;
when the page declares none, the resolver currently falls back to the final
fetched URL, so a non-null value is not proof of a declaration. null for
indexed results. For follow-up lookups use normalizedUrl (indexed) or
resolvedUrl (on-demand), not this field.Indexed example
On-demand example
Errors
See Error Handling and Rate Limits.
SDK equivalents
resolutionMode to index_only.