Skip to main content
POST /stores/search finds stores (retailers) whose observed assortment matches a description, such as linen dresses or Japanese ceramics. Results are ranked by each store’s published assortment profile, plus exact matches on store name or domain. Each result identifies the store and summarizes its profile. To inspect a result, pass its store.primaryDomain to GET /stores/{domain}. To search its products, pass the same domain in stores, or store.catalog in catalogs, on POST /products/search.
Store search covers stores with a published profile, not every covered store. Results can return fewer stores than limit, and there is no total or pagination. Profile counts describe a store’s observed assortment, not products that match your text. Use POST /products/search to establish product-level requirements.
This endpoint is not billed. It is rate limited like every /v1 route. Responses are sent with Cache-Control: private, no-store.

Request

Body parameters

Unknown fields return a 422.
string
required
Description of the kind of store to find, 1 to 500 characters after trimming whitespace.
integer
default:"24"
Most stores to return, from 1 to 100.

Response

StoreSearchResult[]
required
Unique stores, best match first.

Example response

Illustrative values, with one distribution shown:

Errors

See the overview for authentication and rate-limit errors. Operation ID: searchStores. SDK methods: Python search_stores(text, limit=...); TypeScript searchStores({ text, limit }). The CLI command is storerouter stores search <description>. The MCP equivalent is search_stores.