Skip to main content
The StoreRouter search endpoint lets you find products across every catalog your key can access using free-text queries, structured facet filters, and price range constraints — in any combination. Omit 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 call POST /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. Pass a free-text string as q 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 a name 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

Use price_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 combine q, facets, and price filters in a single request. All active filters are applied together.

Restrict search to catalogs

Send catalogs 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 understands q and derives filters from it. These fields let you inspect and adjust that behavior:
  • Every successful page includes effectiveQuery, with or without debug. It reports the text, facets, and bounds that actually ran. Each facet carries source: "caller" for one you sent, or source: "generated" for one understood from q.
  • A facet you send in facets replaces any understood facet of the same name.
  • omit_generated_facets drops an understood facet that is wrong when you have no value of your own for it. Use the names effectiveQuery reports.
  • understand: false matches q as written and filters only by what you send.
  • relax: true drops understood filters in stages when q returns nothing. Facets you send are never dropped unless you mark them "relaxable": true.
  • A facet sent with "relaxable": true may be dropped by relax, so a caller that does its own query understanding can send understand: false, its guesses as relaxable facets, and relax: true to get the staged fallback over them. See facets for the names that may be marked.
  • brand_quality_min and brand_quality_max bound brand quality from 1 (very poor) to 6 (exceptional). similar_to_brands ranks results toward the style of up to 10 brands without filtering.
effectiveQuery is a report, not a request fragment. Don’t send it back as a request body: understood facets of one name can AND together, which a request cannot express.
To match text exactly as written with your own filters, send 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:
To get the full product record with fields like description, sizes, colors, variants, identifiers, and enrichment, use product lookup with the productUrl from a search result.