Skip to main content
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 a 422.
string
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.
boolean
default:"true"
Set to false to match q as written and filter only by the facets and bounds you send. Requires q.
SearchFacet[]
Filters a product must match. A product must match every facet, and any value within a facet. Each facet has a name, a values array, and an optional relaxable flag that defaults to false.
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 "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.
Facet[]
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.
string[]
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.
string[]
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.
number
Inclusive minimum price, at least 0. Combined with any understood minimum by keeping the higher one.
number
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.
number
Inclusive minimum brand quality score, from 1 (very poor) to 6 (exceptional). Combined with any understood bound by keeping the stricter one.
number
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.
string[]
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.
string[]
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.
string[]
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.
integer
default:"50"
Maximum results per page. Accepted range: 1–100.
string
The nextCursor from the previous page, passed back verbatim with the same request body. Omit it on the first request. See Pagination.
boolean
default:"false"
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.
boolean
default:"false"
Reserved for diagnostic detail. effectiveQuery is returned on every response, with or without debug. See Effective query.
boolean
default:"false"
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 a 422:
  • understand: false without q.
  • relax without q, or with understand: false and no facet marked relaxable.
  • A facet marked relaxable whose name no relaxation stage covers, such as gender, product_type, or brand_name.
  • omit_generated_facets without an understood q (a q with understand left on).
  • fallback_category without an understood q, 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 facets or within exclude_facets. Put every accepted value in one facet.
  • A name in both facets and omit_generated_facets. A facet you send already replaces the understood one.
  • More than 50 entries in facets, exclude_facets, or omit_generated_facets.
  • A negative price, or price_min greater than price_max.
  • Brand quality outside 1–6, or brand_quality_min greater than brand_quality_max.
  • similar_to_brands that is empty, has more than 10 names, or has a blank name.
  • catalogs that is empty or has more than 500 keys.
  • stores that is empty, has more than 20 domains, or includes a blank domain; or sending both catalogs and stores.
  • 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

MerchantProductListItem[]
required
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.
string | null
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.
string
required
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.
object
required
The search that actually ran, returned on every page. See Effective query.

Example response

Effective query

Every successful page includes effectiveQuery, with or without debug. It reports the search that actually ran, in the request’s own vocabulary.
object
effectiveQuery is a report, not a request fragment. Understood facets of one name can AND together, which a request cannot express. Don’t send it back as a request body.
This example omits the items array contents for brevity.

Facet names

Use these values for the name 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.
Advance through pages by repeating your request with the same body and the cursor value from the previous response:
  1. Send your initial search request with the desired filters and an optional limit.
  2. If nextCursor is non-null in the response, send a new request with cursor set to that value and all other fields unchanged.
  3. Repeat until nextCursor is null.
Pages are consecutive slices of one ranked list, so they don’t overlap. A search with 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 as search_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.