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./v1 route. Responses are sent with Cache-Control: private, no-store.
Request
Body parameters
Unknown fields return a422.
Description of the kind of store to find, 1 to 500 characters after trimming whitespace.
Response
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.