@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Intelligent Search API
@base https://apiexamples.vtexcommercestable.com.br/api/io/_v/api/intelligent-search
@version 0.1.12
@endpoints 8
@toc top_searches(1), autocomplete_suggestions(1), correction_search(1), banners(1), search_suggestions(1), product_search(1), facets(1), pickup-point-availability(1)

@group top_searches
@endpoint GET /top_searches
@desc Get list of the 10 most searched terms
@optional {locale: str # Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language.}
@returns(200) {searches: [map]} # OK

@endgroup

@group autocomplete_suggestions
@endpoint GET /autocomplete_suggestions
@desc Get list of suggested terms and attributes similar to the search term
@optional {query: str # 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:` or `?query=product.id:` | `?query=product:98765` |
 | SKU ID | `?query=sku:` or `?query=sku.id:` | `?query=sku.id:12345` |
 | Reference ID | `?query=sku.reference:` | `?query=sku.reference:REF123` |
 | EAN | `?query=sku.ean:` | `?query=sku.ean:7891234567890` |
 | Slug | `?query=product.link:` | `?query=product.link:blue-shirt` |, locale: str # Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language.}
@returns(200) {searches: [map]} # OK

@endgroup

@group correction_search
@endpoint GET /correction_search
@desc Get attempt of correction of a misspelled term
@optional {query: str # 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:` or `?query=product.id:` | `?query=product:98765` |
 | SKU ID | `?query=sku:` or `?query=sku.id:` | `?query=sku.id:12345` |
 | Reference ID | `?query=sku.reference:` | `?query=sku.reference:REF123` |
 | EAN | `?query=sku.ean:` | `?query=sku.ean:7891234567890` |
 | Slug | `?query=product.link:` | `?query=product.link:blue-shirt` |, locale: str # Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language.}
@returns(200) {correction: map{misspelled: bool, correction: bool, text: str, highlighted: str}} # OK

@endgroup

@group banners
@endpoint GET /banners/{facets}
@desc Get list of banners registered for query
@required {facets: str=/ # ## 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). |}
@optional {query: str # 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:` or `?query=product.id:` | `?query=product:98765` |
 | SKU ID | `?query=sku:` or `?query=sku.id:` | `?query=sku.id:12345` |
 | Reference ID | `?query=sku.reference:` | `?query=sku.reference:REF123` |
 | EAN | `?query=sku.ean:` | `?query=sku.ean:7891234567890` |
 | Slug | `?query=product.link:` | `?query=product.link:blue-shirt` |, locale: str # Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language.}
@returns(200) {banners: [map]} # OK

@endgroup

@group search_suggestions
@endpoint GET /search_suggestions
@desc Get list of suggested terms similar to the search term
@optional {query: str # 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:` or `?query=product.id:` | `?query=product:98765` |
 | SKU ID | `?query=sku:` or `?query=sku.id:` | `?query=sku.id:12345` |
 | Reference ID | `?query=sku.reference:` | `?query=sku.reference:REF123` |
 | EAN | `?query=sku.ean:` | `?query=sku.ean:7891234567890` |
 | Slug | `?query=product.link:` | `?query=product.link:blue-shirt` |, locale: str # Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language.}
@returns(200) {searches: [map]} # OK

@endgroup

@group product_search
@endpoint GET /product_search/{facets}
@desc Get list of products for a query
@required {facets: str=/ # ## 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). |}
@optional {query: str # 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:` or `?query=product.id:` | `?query=product:98765` |
 | SKU ID | `?query=sku:` or `?query=sku.id:` | `?query=sku.id:12345` |
 | Reference ID | `?query=sku.reference:` | `?query=sku.reference:REF123` |
 | EAN | `?query=sku.ean:` | `?query=sku.ean:7891234567890` |
 | Slug | `?query=product.link:` | `?query=product.link:blue-shirt` |, count: num=24 # Number of products per page., page: num=1 # Current search page., sort: str(price:desc/price:asc/orders:desc/name:desc/name:asc/release:desc/discount:desc) # 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., locale: str # Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language., hideUnavailableItems: bool=false # 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`., simulationBehavior: str(default/skip/only1P)=default # 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., showSponsored: bool=false # Defines if sponsored products are listed (`true`) or not (`false`). Applicable to stores using [VTEX Ads](https://developers.vtex.com/docs/guides/vtex-ads) to offer ad space., sponsoredCount: str # Amount of sponsored products to be returned. Applicable only to merchants using [VTEX Ads](https://developers.vtex.com/docs/guides/vtex-ads)., advertisementPlacement: str(top_search/middle_search/search_shelf/cart_shelf/plp_shelf/autocomplete/homepage) # Advertisement placement. Applicable only to merchants using [VTEX Ads](https://developers.vtex.com/docs/guides/vtex-ads)., repeatSponsoredProducts: bool # 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](https://developers.vtex.com/docs/guides/vtex-ads).}
@returns(200) {products: [map], recordsFiltered: num, correction: map{misspelled: bool}, fuzzy: str, operator: str, translated: bool, pagination: map{count: num, current: map{index: num, proxyUrl: str}, before: [map], after: [map], perPage: num, next: map{index: num, proxyUrl: str}, previous: map{index: num}, first: map{index: num}, last: map{index: num}}} # OK    List of products for the given query.
@errors {400: Bad Request}

@endgroup

@group facets
@endpoint GET /facets/{facets}
@desc Get list of the possible facets for a given query
@required {facets: str=/ # ## 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). |}
@optional {query: str # 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:` or `?query=product.id:` | `?query=product:98765` |
 | SKU ID | `?query=sku:` or `?query=sku.id:` | `?query=sku.id:12345` |
 | Reference ID | `?query=sku.reference:` | `?query=sku.reference:REF123` |
 | EAN | `?query=sku.ean:` | `?query=sku.ean:7891234567890` |
 | Slug | `?query=product.link:` | `?query=product.link:blue-shirt` |, locale: str # Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language., hideUnavailableItems: bool=false # 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`.}
@returns(200) {facets: [map], sampling: bool, breadcrumb: [map], queryArgs: map{query: str, selectedFacets: [map]}, translated: bool} # OK    List of facets for the given query.

@endgroup

@group pickup-point-availability
@endpoint GET /pickup-point-availability/{facets}
@desc Get pickup point availability for Delivery Promise
@required {facets: str=/ # ## 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). |, an: str # Account name. The name of the VTEX account.}
@optional {query: str # 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:` or `?query=product.id:` | `?query=product:98765` |
 | SKU ID | `?query=sku:` or `?query=sku.id:` | `?query=sku.id:12345` |
 | Reference ID | `?query=sku.reference:` | `?query=sku.reference:REF123` |
 | EAN | `?query=sku.ean:` | `?query=sku.ean:7891234567890` |
 | Slug | `?query=product.link:` | `?query=product.link:blue-shirt` |, coordinates: str # Geographic coordinates in the format `longitude,latitude`. Used to calculate distance from pickup points and sort results by proximity. Required when using the country and ZIP code approach., zip-code: str # ZIP code or postal code. Required when using the country and ZIP code approach., country: str # Three-letter country code in [ISO 3166 ALPHA-3](https://www.iban.com/country-codes) format. Required when using the country and ZIP code approach., deliveryZonesHash: str # Pre-computed hash for delivery zones. Used for faster lookup. Required when using the hashes approach (alternative to country and ZIP code)., pickupsHash: str # Pre-computed hash for pickups. Used for faster lookup. Required when using the hashes approach (alternative to country and ZIP code).}
@returns(200) {pickupPointDistances: [map]} # OK

@endgroup

@end