Get list of the possible facets for a given query
Lists the possible facets for a given query.
ℹ️ Migrate to Intelligent Search API v1 for HTTP caching (Cache-Control: public, max-age=600), lower latency, and explicit regionalization without relying on the segment cookie. The new endpoint is: GET List filters for a search. See the migration guide.
⚠️ When possible, use the store's production domain in the URL (for example, https://apiexamples.com/api/io/_v/api/intelligent-search) for a better performance. This is particularly important for headless integrations. In case it's not possible to use the store's production URL, prefer using https://{accountName}.vtexcommercestable.com.br/api/io/_v/api/intelligent-search.
If using this option in a fully headless store with no store domain configured, follow these steps:
- Configure a domain by following the Configuring the store domain guide.
- Send the Host header with the configured domain:
curl --location 'https://{accountName}.vtexcommercestable.com.br/api/io/_v/api/intelligent-search/facets/' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Host: {configured domain}'
Permissions
This endpoint does not require authentication or permissions.
Path parameters
Format
The facets parameter follows the format: /${facetKey1}/${facetValue1}/${facetKey2}/${facetValue2}/.../${facetKeyN}/${facetValueN}.
⚠️ Required: Only the trade-policy facet is mandatory. All other facets are optional filters.
The order in which the terms appear is not relevant to the search.
You can also repeat the same facetKey several times for different values. For example: category-1/shoes/color/blue/color/red/color/yellow.
Filter combinations
When shoppers apply filters, the API combines them according to the following rules:
- Facets of the same type → OR (union): When multiple values of the same facet are applied, the API returns the union of all products matching any of those values.
- Facets of different types → AND (intersection): When different facet types are combined, the API returns only the products that satisfy all selected facet conditions simultaneously.
Negative filters (NOT operator)
To exclude a facet value, prefix the value with not: in the path segment: /{facetKey}/not:{facetValue}/. For example, color/blue/size/not:42 keeps color blue and excludes size 42. Use the same not: prefix with the facet keys and values configured in your catalog. This supports use cases such as including products in one collection but excluding another.
The NOT operator excludes specific values. The OR and AND rules in Filter combinations still describe how multiple positive facet selections combine.
Available filters
The facets parameter allows the following filters:
| facetKey | Description | Example |
|---|---|---|
| trade-policy (required) | Filter by trade policy (sales channel) using trade-policy/{tradePolicyId}. Some integrations use the salesChannel query string for the same purpose when supported. | trade-policy/2 |
| category-${n} (optional) | Filter the search by category, where n represents the category tree level (1 = department, 2 = category, 3 = subcategory, and so on). Declare the full path from the root level through every parent down to the level you need. For example, using only category-2/shirts without the category-1/... segment is incorrect. | category-1/clothing/category-2/shirts |
| brand (optional) | Filter by brand slug or identifier. | brand/acme |
| {specificationName} (optional) | Filter by a catalog specification exposed as a search filter, using {specificationName}/{specificationValue} (for example color/blue). | color/blue |
| productClusterIds (optional) | Filter by collection ID. | productClusterIds/262 |
| price (optional) | Filter by price range ${minPrice}:${maxPrice}. | trade-policy/1/color/blue/price/100:500 (with ?query=shirt on the full URL when using a text query). |
Query parameters
Search term. It can contain any character.
This parameter is named query in the API. The short form q is an alias for query and has the same semantics.
You can search for products or SKUs using specific ID types by adding search parameters (query) at the end of the store URL, respecting one of the following structures:
- Single item search: ?query=[id type]:[id_1]. Example: ?query=product:98765
- Multiple items search: ?query=[id type]:[id_1];[id_2];[id_3]. Example: ?query=product:98765;98743
⚠️ All searched IDs should be of the same type.
Search by ID
On the Intelligent Search API, search products or SKUs by ID by sending the value in the query or q query parameter on requests such as /product_search/{facets}. The {facets} path must include the required trade-policy facet and any optional filters.
- Product ID: .../product_search/trade-policy/1?query=product:98765 or .../product_search/trade-policy/1?query=product.id:98765.
- SKU ID: .../product_search/trade-policy/1?query=sku.id:12345 or .../product_search/trade-policy/1?query=sku:12345.
Supported ID types
The possible value types for the ID segment are product.id, sku.id, sku.ean, sku.reference, product.link, or id (ProductID, ProductRefID, SKUID, SKURefID, and EAN).
| ID Type | Query format | Example |
|---|---|---|
| Product ID | ?query=product:<id> or ?query=product.id:<id> | ?query=product:98765 |
| SKU ID | ?query=sku:<id> or ?query=sku.id:<id> | ?query=sku.id:12345 |
| Reference ID | ?query=sku.reference:<id> | ?query=sku.reference:REF123 |
| EAN | ?query=sku.ean:<id> | ?query=sku.ean:7891234567890 |
| Slug | ?query=product.link:<link> | ?query=product.link:blue-shirt |
Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language.
Defines whether the result should hide unavailable items (true), or not (false). When set to true, only products with stock are returned; when set to false, the API includes unavailable products as well. A product is considered unavailable when availableQuantity = 0, while availableQuantity = 10000 indicates that the product is available. Retailers may choose to show unavailable items for commercial reasons (for example, to signal that they offer those products even if temporarily out-of-stock). The recommended default is true.
When true, hidden facets are omitted from the response.
Response
OK
List of facets for the given query.