> For the complete documentation index, see [llms.txt](https://docs.globo.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.globo.io/api-reference/search-products.md).

# Search products

Search products, collections, and get keyword suggestions from your store's search index.

## 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](/api-reference/api-access-and-authentication.md).

## 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](/api-reference/get-filter-products.md#parameters). |
| `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

```json
{
  "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](/api-reference/get-filter-products.md#response).
* `suggestions` — related search terms, each `{"keyword": "..."}`. Populated depending on your store's search suggestion settings — see [Before search](/search/show-suggestions-before-typing.md) and [No results](/search/show-suggestion-when-no-search-result-found.md).
* `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](/api-reference/api-access-and-authentication.md) for the shared `401`/`403`/`429` cases.

## Related pages

* [API access & authentication](/api-reference/api-access-and-authentication.md)
* [Get filtered products](/api-reference/get-filter-products.md)