POST /products/search searches indexed products by free text, filters, or both. Results span every catalog your key can access unless catalogs narrows them. The response returns a page of MerchantProductListItem objects and an opaque nextCursor for advancing through results.
Each field controls one thing. q says what to find. facets, exclude_facets, and the bounds say what to keep. catalogs says where to look. limit and cursor page through results. A request that combines fields in a contradictory way returns a 422 instead of being resolved silently.
If you already have a source product and want similar products, use POST /products/more-like-this.
The MCP search_products tool accepts this same request body as its flat arguments and returns this same successful page.
Request
Body parameters
Every field is optional. Unknown fields return a422.
Free-text query, up to 1,000 characters. Omit it, or send a blank string, to browse by filters alone. By default,
q is understood: StoreRouter rewrites it for retrieval and derives category, gender, color, brand, price, and attribute filters from it.Set to
false to match q as written and filter only by the facets and bounds you send. Requires q.Filters a product must match. A product must match every facet, and any value within a facet. Each facet has a A facet you send replaces any understood facet of the same name. A color facet replaces both understood color facets. Each name may appear at most once, and the list takes at most 50 entries. See Facet names for the supported names.A facet is never relaxed unless you send it with
name, a values array, and an optional relaxable flag that defaults to false."relaxable": true. A relaxable facet still filters until a relaxation stage drops it, and with relax: false it is never dropped. This is how a caller that does its own query understanding gets the staged fallback over its own guesses: send q with understand: false, the guesses as relaxable facets, and relax: true. Only a name a relaxation stage covers may be marked: brand profile facets, taxonomy attributes, color, color_family, and category_path.depth_2 and deeper. Any other name returns a 422.Filters a product must not match. Products with any listed value of any listed facet are removed. Each name may appear at most once, and the list takes at most 50 entries.
Names of understood facets to drop before searching. Use it for a derived filter that is wrong when you have no value of your own for it. To replace a derived filter instead, send a facet of that name in
facets.Use the names that effectiveQuery reports. Color is omitted per axis (color or color_family). Requires an understood q. A name may not also appear in facets. The list takes at most 50 entries.Category path, root first, with 1–4 taxonomy category names, for example
["apparel & accessories", "clothing"]. Requires q with understand: true. It applies only when understanding finds no root category and your facets contain no category filter. Applied levels appear as generated facets in effectiveQuery, so relaxation and omit_generated_facets can remove them.Inclusive minimum price, at least
0. Combined with any understood minimum by keeping the higher one.Inclusive maximum price, at least
0. Combined with any understood maximum by keeping the lower one. Must be greater than or equal to price_min.Inclusive minimum brand quality score, from
1 (very poor) to 6 (exceptional). Combined with any understood bound by keeping the stricter one.Inclusive maximum brand quality score, from
1 to 6. Combined with any understood bound by keeping the stricter one. Must be greater than or equal to brand_quality_min.1 to 10 non-empty brand names whose style to favor. Ranks products by similarity to these brands’ aesthetic; it does not filter. Replaces any brands understood from
q.1 to 500 catalog keys to search. Omit both selectors to search every catalog your key can access. Keys your key cannot access match nothing. Cannot be combined with
stores.1 to 20 store domains, such as
allbirds.com. Domains are matched without case or a leading www.; each searches every catalog serving it within your scope. An uncovered domain returns 404 with domain_not_covered. Check a domain with GET /stores/{domain}, or find stores with POST /stores/search. Cannot be combined with catalogs.The
nextCursor from the previous page, passed back verbatim with the same request body. Omit it on the first request. See Pagination.When
q returns nothing, retry with filters dropped in stages and return the first stage with results. Inferred brand attributes are dropped first, then attributes, then color and deep categories. Relaxation drops understood filters and the facets you marked relaxable; any other facet you send is never dropped. Requires q, and either understand left on or at least one relaxable facet. A relaxed page’s cursor continues the same relaxed results.Reserved for diagnostic detail.
effectiveQuery is returned on every response, with or without debug. See Effective query.Spreads page 1 across retailers and removes products whose image repeats one already on the page. Applies only to page 1, with no effect when you send
catalogs, your key is limited to specific catalogs, or you filter by brand_name. Keep the same value when continuing a cursor.Validation rules
The API rejects these requests with a422:
understand: falsewithoutq.relaxwithoutq, or withunderstand: falseand no facet markedrelaxable.- A facet marked
relaxablewhose name no relaxation stage covers, such asgender,product_type, orbrand_name. omit_generated_facetswithout an understoodq(aqwithunderstandleft on).fallback_categorywithout an understoodq, with fewer than 1 or more than 4 levels, or with a path that does not exist in the taxonomy.- A facet name repeated within
facetsor withinexclude_facets. Put every accepted value in one facet. - A name in both
facetsandomit_generated_facets. A facet you send already replaces the understood one. - More than 50 entries in
facets,exclude_facets, oromit_generated_facets. - A negative price, or
price_mingreater thanprice_max. - Brand quality outside 1–6, or
brand_quality_mingreater thanbrand_quality_max. similar_to_brandsthat is empty, has more than 10 names, or has a blank name.catalogsthat is empty or has more than 500 keys.storesthat is empty, has more than 20 domains, or includes a blank domain; or sending bothcatalogsandstores.- An unknown facet name, or an unknown field anywhere in the body.
Removed fields
catalog and text_search_query are no longer accepted. A request that sends either returns a 422 whose message names the replacement:
Example
Response
The current page of product results. See the Product model for the full field reference. If your organization has scoped options enabled, follow the Black + Tall example to retrieve a look by its
prd- ID.Opaque cursor for the next page of results. Pass it back verbatim as
cursor with the same request body. null when you have reached the last page. Keep de-duplicating by uuid when using diversity or when catalogs change; see Pagination.Server-generated UUID for this execution, matching
X-Request-ID. Each invocation or page gets a fresh ID, even when you reuse X-Request-ID.The search that actually ran, returned on every page. See Effective query.
Example response
Effective query
Every successful page includeseffectiveQuery, with or without debug. It reports the search that actually ran, in the request’s own vocabulary.
items array contents for brevity.
Facet names
Use these values for thename field in each facet object. Each facet has one public spelling, and unknown names return a 422. Facet values are canonical lowercase handles and may contain spaces.
You can also filter on brand profile facets, such as
brand_origin_country, and on taxonomy attribute handles by their bare name, such as fit. Don’t add the attribute_facets. prefix: attribute_facets.fit returns a 422. The one exception is the attribute named color, which you send as attribute_facets.color because color already names the facet above.
To discover valid values, list categories and their category_path.depth_N facets with GET /taxonomy/categories, a category’s attributes with GET /taxonomy/attributes, and an attribute’s value handles with GET /taxonomy/attributes/{handle}/values. To see how many products each value would return under your filters, use POST /products/facet-counts.
Pagination
For a detailed walkthrough of cursor-based pagination, see Pagination guide.
cursor value from the previous response:
- Send your initial search request with the desired filters and an optional
limit. - If
nextCursoris non-null in the response, send a new request withcursorset to that value and all other fields unchanged. - Repeat until
nextCursorisnull.
q ranks a bounded set of products, so it ends after a limited number of pages. A product can still repeat if the catalog changes between requests, so de-duplicate by uuid when you concatenate pages.
Cursors are opaque — don’t parse or construct them. Pass back exactly the nextCursor the previous page returned. A cursor that is malformed, was issued under a different cursor version, or no longer maps onto the current query returns 400 with {"detail": "invalid cursor"}. Restart from page 1 by omitting cursor.
SDK equivalents
The Python and TypeScript SDKs expose this endpoint assearch_products and searchProducts. Both check most of the validation rules locally and fail before sending a request. See the Python SDK and TypeScript SDK references.