Get list of products for a query
Lists the active products 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 Search products. If you need to look up a single product by a known identifier (for a product detail page), use the new GET Get product endpoint. It skips the search pipeline entirely, reducing latency and improving cache-hit rates. See the migration guide.
⚠️ Required facet: Only the trade-policy facet is required in the path. All other facets (such as productClusterIds, category, color, etc.) are optional filters that can be used to narrow down the search results. When no additional facets are provided, all products for the trade policy will be returned.
⚠️ 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/product_search/' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Host: {configured domain}'
Sponsored products (VTEX Ads)
The query parameters showSponsored, sponsoredCount, advertisementPlacement, and repeatSponsoredProducts apply only to stores using VTEX Ads. See each parameter for behavior details.
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 |
Number of products per page.
Current search page.
Defines how results are sorted. Relevance is Intelligent Search's default sorting type, used for typical product search and applied when this parameter is omitted, null or empty. Use one of the other values listed below only when you need a fixed sort instead of relevance.
Allowed values:
- Omitted, empty, or null (default): Results are sorted by relevance.
- price:desc: Results are sorted by price in descending order, from highest to lowest.
- price:asc: Results are sorted by price in ascending order, from lowest to highest.
- orders:desc: Results are sorted by the amount of orders in the past 90 days, in descending order.
- name:desc: Results are sorted by name in descending alphabetical order.
- name:asc: Results are sorted by name in ascending alphabetical order.
- release:desc: Results are sorted by release date in descending order, from most recent to least recent.
- discount:desc: Results are sorted by discount percentage in descending order, from highest to lowest.
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.
Defines the simulation behavior.
- default - Calls the simulation for every single seller.
- skip - Never calls the simulation.
- only1P - Only calls the simulation for first-party sellers.
- only3P - Only calls the simulation for third-party sellers.
- regionalize1p - Calls regionalized simulation for first-party sellers only.
Defines if sponsored products are listed (true) or not (false). Applicable to stores using VTEX Ads to offer ad space.
Amount of sponsored products to be returned. Applicable only to merchants using VTEX Ads.
Advertisement placement. Applicable only to merchants using VTEX Ads.
Defines if sponsored products can appear again as organic listings. When set as true, it allows the same product to be shown as both sponsored and organic. When set as false, it removes duplicates, ensuring a sponsored product does not appear again as organic. Applicable only to merchants using VTEX Ads.
Response
OK
List of products for the given query.