Search products

What this does

Runs a search against your store’s product catalog (and optionally collections) using the same search engine as the app’s storefront search widget — typo tolerance, synonyms, and relevance ranking all apply the same way here as they do on your storefront.

Endpoint

GET /sfs/v1/search

Requires the read:catalog scope. See API access & authentication.

Parameters

Omitting term returns your store’s zero-character suggestions/results (if configured) instead of a keyword search.

Parameter	Required	Type	Example	Description
term	Optional	string	boots	The search keyword. Truncated at 512 characters.
page	Optional	integer	1	Page number for matched products. Defaults to 1.
limit	Optional	integer	50	Products per page. Defaults to your store’s instant-search product limit (capped at 48); when passed, capped at 200.
sort	Optional	string	relevance	Sort order for matched products. Defaults to relevance; also accepts sort_by as an alias, with the same title-*, price-*, created-*, best-selling, sale-* values as Get filtered products.
tags	Optional	array	tags[]=vip	Only include products with these tags.
exclude_tags	Optional	array	exclude_tags[]=hidden	Exclude products with these tags.
locale	Optional	string	de	Storefront locale — only applied if your store has more than one language configured.
currency	Optional	string	CAD	Presentment currency — only applied if multi-currency is enabled.
country	Optional	string	CA	Country context for Shopify Markets pricing.
catalog_ids	Optional	array	catalog_ids[]=10	B2B catalog IDs.
company_location_id	Optional	string	998877	B2B company location ID.
company_location_country	Optional	string	US	B2B company location country; falls back to country if omitted.
rate	Optional	number	1	Currency conversion rate applied to displayed prices. Defaults to 1.
adjustment	Optional	number	1	Price adjustment multiplier. Defaults to 1.

Response

{
  "result": {
    "isEmpty": false,
    "term": "boots",
    "products": [ { "id": ..., "handle": ..., "title": ..., "...": "..." } ],
    "suggestions": [ { "keyword": "boots for men" } ],
    "popular_keywords": [ { "keyword": "sneakers" } ],
    "total_product": 42,
    "pagination": {
      "from": 1,
      "to": 50,
      "total": 42,
      "per_page": 50,
      "current_page": 1,
      "last_page": 1,
      "hasMorePages": false
    },
    "collections": [ { "...": "..." } ]
  }
}

Everything lives under a top-level result key.

• isEmpty — true when nothing matched (no products, collections, or suggestions).
• products — matched products, same document shape as Get filtered products.
• suggestions — related search terms, each {"keyword": "..."}. Populated depending on your store’s search suggestion settings — see Before search and No results.
• popular_keywords — only present on the zero-character/empty-term response.
• total_product — total matching product count for the query, before pagination.
• pagination — page/offset info for the current page/limit (products only).
• collections — matched collections, if your store has collection search enabled.

Not every key is present on every response — they’re only included when relevant to your query and your store’s search settings.

Errors

See API access & authentication for the shared 401/403/429 cases.

Related pages

• API access & authentication
• Get filtered products

Was this helpful?

Report an issue