catalogs to search every catalog your key can access. Send catalogs with a list of catalog keys when you want to restrict search to those catalogs.
How search works
When you callPOST /v1/products/search, StoreRouter runs the query against every catalog your key can access, or only the catalogs listed in catalogs. Each field controls one thing, and a request that combines fields in a contradictory way returns a 422. See the validation rules.
By default, StoreRouter understands q: it rewrites the text for retrieval and derives filters such as category, gender, color, brand, and price from it. See Control query understanding to inspect or override those derived filters.
The response returns a page of matching items and an opaque nextCursor you use to fetch subsequent pages. Each item in items is a lightweight product record — enough to render a card or feed a ranking model — while the full canonical record is available via product lookup.
If you already have a source product and want similar items, use More Like This instead of inventing a keyword query.
Basic keyword search
Pass a free-text string asq to search by keyword. Omit q entirely to browse without any keyword filter.
Faceted filtering
Facets let you filter by structured product attributes. Each facet is an object with aname and a values array. You can apply multiple facets in a single request — the filters are combined with AND logic, so each additional facet narrows the result set. A product matches a facet when it has any of the listed values. Each facet name may appear only once in facets.
Commonly used facet names:
Facet values are canonical lowercase handles and may contain spaces. You can also filter on taxonomy attribute handles by their bare name, such as
fit. The attribute_facets. prefix is not accepted, except for attribute_facets.color. See Facet names for the full list.
To remove products instead, send the same facet shape in exclude_facets. For example, "exclude_facets": [{"name": "brand_name", "values": ["acme"]}] drops one brand.
Price range filtering
Useprice_min and price_max to restrict results to a price range. Both bounds are inclusive. You can use either bound on its own.
Combined example: keyword, facets, and price range
You can combineq, facets, and price filters in a single request. All active filters are applied together.
Restrict search to catalogs
Sendcatalogs with 1 to 500 catalog keys to search only those catalogs. Keys your key cannot access match nothing. Omit catalogs to search every catalog your key can access.
The single-valued
catalog field was removed and now returns a 422. Send catalogs: ["<key>"] instead.Control query understanding
By default, StoreRouter understandsq and derives filters from it. These fields let you inspect and adjust that behavior:
- Every successful page includes
effectiveQuery, with or withoutdebug. It reports the text, facets, and bounds that actually ran. Each facet carriessource: "caller"for one you sent, orsource: "generated"for one understood fromq. - A facet you send in
facetsreplaces any understood facet of the same name. omit_generated_facetsdrops an understood facet that is wrong when you have no value of your own for it. Use the nameseffectiveQueryreports.understand: falsematchesqas written and filters only by what you send.relax: truedrops understood filters in stages whenqreturns nothing. Facets you send are never dropped unless you mark them"relaxable": true.- A facet sent with
"relaxable": truemay be dropped byrelax, so a caller that does its own query understanding can sendunderstand: false, its guesses as relaxable facets, andrelax: trueto get the staged fallback over them. Seefacetsfor the names that may be marked. brand_quality_minandbrand_quality_maxbound brand quality from1(very poor) to6(exceptional).similar_to_brandsranks results toward the style of up to 10 brands without filtering.
q with understand: false. This replaces the removed text_search_query field:
Understanding results
Each search response contains these top-level fields:
Each item in
items contains the following fields: