POST /v1/products/more-like-this when you already have a product and want related items. Use POST /v1/products/search when the user starts from a keyword, facets, or an arbitrary price range.
Basic similar-products request
Scope to specific catalogs
Omitcatalogs to search across all active crawled catalogs. Pass catalogs, a list of 1–100 catalog keys, to restrict results to those catalogs — for example, a one-entry list when a related-products rail should stay within the same merchant. The source product itself may live outside the list:
Choose relative price behavior
price_preference is relative to the source product’s currentPrice:
Add facets, exclusions, and bounds
More Like This takes the same caller controls as catalog search:facetslists filters a product must match. A facet you send replaces the generated facet of the same name, and it is never relaxed.exclude_facetsremoves products that match any listed value.price_min/price_maxbound price. They combine withprice_preferenceby keeping the tighter bound.brand_quality_min/brand_quality_maxbound brand quality, from 1 (very poor) to 6 (exceptional).
facets or exclude_facets.
Relaxation
More Like This builds its query from facets StoreRouter generates from the source product: category, gender, color, and attributes. When those facets leave page 1 short,relax retries with generated facets dropped in stages, least trusted first. It returns the first stage that fills the page.
relax defaults to true on More Like This. Search defaults to false. Both routes follow the same rule: what you send is never silently dropped, but StoreRouter may drop its own inferences.
- On search, the generated facets come from the shopper’s words in
q, so dropping them silently would ignore what the caller said. - On More Like This there is no caller text. The generated facets are StoreRouter’s inference from the source product.
facets, exclude_facets, and price and brand-quality bounds are never dropped.
When relaxation runs depends on the source:
Send
relax: false to keep every generated facet. A relaxed page’s nextCursor continues the same relaxed results. Sending that cursor with relax: false returns 400.
Debug the derived query
Setdebug: true to inspect the public, server-derived query fields used for retrieval:
effectiveQuery with fields such as text, retrievalEmbeddingColumns, facets, priceMin, priceMax, and limit. With relax: true (the default), it also carries relaxation, in the same shape search uses:
rounds: stages applied to produce this page,0if none;declinedRounds: stages tried that did not fill the page;droppedFacets: the generated facets dropped.
Paginate similar products
More Like This uses the same cursor model as search. When a response containsnextCursor, pass it back as cursor with the same source and filters: