{ "openapi": "3.0.0", "info": { "version": "0.1.0", "title": "Intelligent Search API v1", "description": "[VTEX Intelligent Search](https://help.vtex.com/docs/tracks/overview-intelligent-search) is search solution for digital commerce that delivers relevant product results, autocomplete suggestions, and personalized experiences based on the catalog from the user's first interaction with the store. This API enables headless implementations to integrate VTEX Intelligent Search capabilities into custom storefronts.\r\n\r\nThis reference documents **Intelligent Search API v1**, which replaces the [Intelligent Search API (Legacy)](https://developers.vtex.com/docs/api-reference/intelligent-search-api) at `/api/io/_v/api/intelligent-search/*`.\r\n\r\n>ℹ️ If you are migrating from the legacy API, see [Migrating to Intelligent Search API v1](https://developers.vtex.com/docs/guides/migrating-to-intelligent-search-api-v1).\r\n\r\n## Common Parameters\r\n\r\n| Parameter | Description |\r\n| --- | --- |\r\n| `{{accountName}}` | Name of your VTEX account. Used in the base URL. |\r\n| `{{environment}}` | Environment to use. Typically `vtexcommercestable` for production. |", "license": { "name": "MIT" } }, "servers": [ { "url": "https://{accountName}.{environment}.com.br/api/intelligent-search/v1", "description": "VTEX Intelligent Search v1 server URL.", "variables": { "accountName": { "default": "apiexamples", "description": "Name of the VTEX account. Used as part of the URL." }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/top-searches": { "get": { "summary": "Get list of the 10 most searched terms", "description": "Lists the 10 most searched terms in the past 14 days.\r\n\r\nFor more information, check the Intelligent Search [Autocomplete](https://help.vtex.com/docs/tutorials/autocomplete) guide.\r\n\r\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "tags": [ "Autocomplete" ], "parameters": [ { "$ref": "#/components/parameters/locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopSearches" }, "example": { "searches": [ { "term": "home", "count": 14 }, { "term": "shirt", "count": 10 }, { "term": "top", "count": 9 }, { "term": "tops", "count": 6 }, { "term": "camera", "count": 5 }, { "term": "kit", "count": 5 }, { "term": "work shirt", "count": 2 }, { "term": "shirts", "count": 2 }, { "term": "clothing", "count": 2 }, { "term": "classic shoes", "count": 1 } ] } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad request. Invalid parameters or missing account context." }, "500": { "description": "Internal server error or upstream failure." } } } }, "/autocomplete-suggestions": { "get": { "summary": "Get list of suggested terms and attributes similar to the search term", "description": "Lists the suggested terms and attributes similar to the search term.\r\n\r\nFor more information, check the Intelligent Search [Autocomplete](https://help.vtex.com/docs/tutorials/autocomplete) guide.\r\n\r\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\n\nIf `query` is missing or empty, the response is `{ \"searches\": [] }`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "tags": [ "Autocomplete" ], "parameters": [ { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutocompleteSearchSuggestions" }, "example": { "searches": [ { "term": "tv", "count": 28861, "attributes": [ { "key": "department", "value": "tvs-and-video", "labelKey": "Department", "labelValue": "TVs and Video" } ] }, { "term": "smarth tv", "count": 2308 }, { "term": "rack tv", "count": 589 } ] } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad request. Invalid parameters or missing account context." }, "500": { "description": "Internal server error or upstream failure." } } } }, "/search-suggestions": { "get": { "summary": "Get list of suggested terms similar to the search term", "description": "Lists suggested terms similar to the search term.\r\n\r\nFor more information, check the Intelligent Search [Autocomplete](https://help.vtex.com/docs/tutorials/autocomplete) guide.\r\n\r\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\n\nIf `query` is missing, empty, or whitespace-only, the response is `{ \"searches\": [] }`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "tags": [ "Autocomplete" ], "parameters": [ { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchSuggestions" }, "example": { "searches": [ { "term": "mountain bike", "count": 66 }, { "term": "bike helmet", "count": 121 }, { "term": "electric bike", "count": 78 } ] } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad request. Invalid parameters or missing account context." }, "500": { "description": "Internal server error or upstream failure." } } } }, "/correction-search": { "get": { "summary": "Get attempt of correction of a misspelled term", "description": "Tries to correct a misspelled term from the search.\r\n\r\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\n\nIf `query` is missing, empty, or whitespace-only, the response is `{\"correction\": {\"correction\": false, \"misspelled\": false, \"text\": \"\", \"highlighted\": \"\"}}`.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "tags": [ "Product list page" ], "parameters": [ { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Correction" }, "example": { "correction": { "correction": true, "misspelled": true, "text": "mountain bike", "highlighted": "mountain bike" } } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad request. Invalid parameters or missing account context." }, "500": { "description": "Internal server error or upstream failure." } } } }, "/banners/{facets}": { "get": { "summary": "Get list of banners registered for query", "description": "Lists the banners registered for a given query. Check the [configuring banners documentation](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/4ViKEivLJtJsvpaW0aqIQ5) for a full explanation of the banner feature.\r\n\r\n>ℹ️ **Segment context:** Intelligent Search API (Legacy) previously read `locale` from `segment.cultureInfo` in the VTEX segment cookie. In v1, pass it directly as a query parameter.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "tags": [ "Product list page" ], "parameters": [ { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/facetsPath" }, { "$ref": "#/components/parameters/locale" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Banners" }, "example": { "banners": [ { "id": "summersale", "name": "Summer Sale", "area": "1", "html": "

This is a test

" } ] } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad request. Invalid parameters or missing account context." }, "500": { "description": "Internal server error or upstream failure." } } } }, "/product-search/{facets}": { "get": { "summary": "Search products", "description": "Lists the active products for a given query.\r\n\r\n>⚠️ **Fetching a single known product?** Use `GET` [Get product](https://developers.vtex.com/docs/api-reference/intelligent-search-api-v1#get-/products) instead. It skips the search pipeline (lower latency) and caches better.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability. Responses containing sponsored products are not cached.\r\n\r\n>ℹ️ **Segment context:** Several parameters on this endpoint replace values previously read from the VTEX segment cookie. See [Migrating from segment](#migrating-from-segment) below.\r\n\r\n## Migrating from segment\r\n\r\nIntelligent Search API (Legacy) reads the following values from the VTEX segment cookie. In v1, pass each one directly as a query parameter:\r\n\r\n| v1 parameter | Segment source |\r\n|:---|:---|\r\n| `locale` | `segment.cultureInfo` |\r\n| `sc` | `segment.channel` |\r\n| `regionId` | `segment.regionId` |\r\n| `country` | `segment.countryCode` or `country` key in `segment.facets` |\r\n| `zip-code` | `zip-code` key in `segment.facets` |\r\n| `coordinates` | `coordinates` key in `segment.facets` |\r\n| `pickupPoint` | `pickupPoint` key in `segment.facets` |\r\n| `deliveryZonesHash` | `deliveryZonesHash` key in `segment.facets` |\r\n| `pickupPointsHash` | `pickupPointsHash` key in `segment.facets` |\r\n| `utmSource` | `segment.utm_source` |\r\n| `utmCampaign` | `segment.utm_campaign` |\r\n| `utmiCampaign` | `segment.utmi_campaign` |\r\n| `campaigns` | `segment.campaigns` |\r\n| `priceTables` | `segment.priceTables` |\r\n\r\nAll other keys in `segment.facets` must be appended to the URL path as `key/value` pairs.\r\n\r\n
\r\nTypeScript reference implementation\r\n\r\nThe following TypeScript snippet shows the full translation:\r\n\r\n```typescript\r\ntype Segment = {\r\n channel?: string | number\r\n regionId?: string\r\n countryCode?: string\r\n cultureInfo?: string\r\n // Semicolon-separated \"key=value\" string, e.g. \"zip-code=22250-040;country=BRA\"\r\n facets?: string\r\n utm_source?: string\r\n utm_campaign?: string\r\n utmi_campaign?: string\r\n campaigns?: string\r\n priceTables?: string\r\n}\r\n\r\nconst SHIPPING_KEYS = new Set([\r\n 'zip-code', 'coordinates', 'country', 'pickupPoint',\r\n 'deliveryZonesHash', 'pickupPointsHash',\r\n])\r\n\r\nfunction segmentToProductSearchV1(segment: Segment, query?: string): string {\r\n const shipping: Record = {}\r\n const pathFacets: Array<{ key: string; value: string }> = []\r\n\r\n for (const pair of (segment.facets ?? '').split(';')) {\r\n const eq = pair.indexOf('=')\r\n if (eq < 0) continue\r\n const key = pair.slice(0, eq)\r\n const value = pair.slice(eq + 1)\r\n if (!key || !value) continue\r\n\r\n if (SHIPPING_KEYS.has(key)) {\r\n shipping[key] = value\r\n } else {\r\n pathFacets.push({ key, value })\r\n }\r\n }\r\n\r\n const params: Record = {}\r\n const set = (name: string, value?: string | number) => {\r\n if (value !== undefined && value !== null && value !== '') {\r\n params[name] = String(value)\r\n }\r\n }\r\n\r\n set('sc', segment.channel)\r\n set('locale', segment.cultureInfo)\r\n set('regionId', segment.regionId)\r\n set('country', segment.countryCode ?? shipping.country)\r\n set('zip-code', shipping['zip-code'])\r\n set('coordinates', shipping.coordinates)\r\n set('pickupPoint', shipping.pickupPoint)\r\n set('deliveryZonesHash', shipping.deliveryZonesHash)\r\n set('pickupPointsHash', shipping.pickupPointsHash)\r\n set('utmSource', segment.utm_source)\r\n set('utmCampaign', segment.utm_campaign)\r\n set('utmiCampaign', segment.utmi_campaign)\r\n set('campaigns', segment.campaigns)\r\n set('priceTables', segment.priceTables)\r\n\r\n if (query) params.query = query\r\n\r\n const facetPath = pathFacets.map(f => `${f.key}/${f.value}`).join('/')\r\n const search = new URLSearchParams(params).toString()\r\n\r\n return `https://{accountName}.vtexcommercestable.com.br/api/intelligent-search/v1/product-search${facetPath ? `/${facetPath}` : ''}?${search}`\r\n}\r\n```\r\n\r\n
\r\n\r\n## Sponsored products (VTEX Ads)\r\n\r\nThe query parameters **`showSponsored`**, **`sponsoredCount`**, **`advertisementPlacement`**, and **`repeatSponsoredProducts`** apply only to stores using [VTEX Ads](https://developers.vtex.com/docs/guides/vtex-ads). Sponsored products are merged into the `products` array.\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "tags": [ "Product list page" ], "parameters": [ { "$ref": "#/components/parameters/facetsPath" }, { "$ref": "#/components/parameters/query" }, { "in": "query", "name": "count", "description": "Number of products per page.", "schema": { "type": "number", "nullable": true, "default": 24 } }, { "in": "query", "name": "page", "description": "Current search page.", "schema": { "type": "number", "nullable": true, "default": 1 } }, { "in": "query", "name": "sort", "description": "Defines how results are sorted. Relevance is the **default** sorting type, applied when this parameter is omitted, null, or empty.\r\n\r\nAllowed values:\r\n- **Omitted, empty, or null** (default): Results are sorted by relevance.\r\n- `:desc` or `:asc`: Results are sorted by any Specification attribute in the store, in descending or ascending order. Replace `` with the specification name in kebab-case (for example, `test:desc` or `color:asc`).\r\n\r\nBuilt-in sorting options:\r\n- `price:desc`: Results are sorted by price in descending order.\r\n- `price:asc`: Results are sorted by price in ascending order.\r\n- `orders:desc`: Results are sorted by the amount of orders in the past 90 days, in descending order.\r\n- `name:desc`: Results are sorted by name in descending alphabetical order.\r\n- `name:asc`: Results are sorted by name in ascending alphabetical order.\r\n- `release:desc`: Results are sorted by release date in descending order.\r\n- `discount:desc`: Results are sorted by discount percentage in descending order.", "schema": { "type": "string", "nullable": true, "example": "price:desc" } }, { "$ref": "#/components/parameters/locale" }, { "$ref": "#/components/parameters/hideUnavailableItems" }, { "$ref": "#/components/parameters/simulationBehavior" }, { "$ref": "#/components/parameters/sc" }, { "$ref": "#/components/parameters/regionId" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/zipCode" }, { "$ref": "#/components/parameters/coordinates" }, { "$ref": "#/components/parameters/pickupPoint" }, { "$ref": "#/components/parameters/deliveryZonesHash" }, { "$ref": "#/components/parameters/pickupPointsHash" }, { "$ref": "#/components/parameters/dpPreview" }, { "$ref": "#/components/parameters/utmSource" }, { "$ref": "#/components/parameters/utmCampaign" }, { "$ref": "#/components/parameters/utmiCampaign" }, { "$ref": "#/components/parameters/campaigns" }, { "$ref": "#/components/parameters/priceTables" }, { "in": "query", "name": "showSponsored", "description": "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.", "schema": { "type": "boolean", "nullable": true, "default": false } }, { "$ref": "#/components/parameters/sponsoredCount" }, { "$ref": "#/components/parameters/advertisementPlacement" }, { "$ref": "#/components/parameters/repeatSponsoredProducts" } ], "responses": { "200": { "description": "OK\r\n\r\nList of products for the given query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductSearch" }, "example": { "products": [ { "cacheId": "sp-2000003", "productId": "2000003", "description": "Introducing our exquisite Top Wood Clock.", "productName": "Top Wood Clock", "productReference": "clock120", "linkText": "wood-clock", "brand": "Sony", "brandId": 2000005, "link": "/wood-clock/p", "categories": [ "/Home & Decor/" ], "categoryId": "40", "categoriesIds": [ "/40/" ], "priceRange": { "sellingPrice": { "highPrice": 197.99, "lowPrice": 197.99 }, "listPrice": { "highPrice": 197.99, "lowPrice": 197.99 } }, "specificationGroups": [], "skuSpecifications": [], "productClusters": [], "clusterHighlights": [], "properties": [], "items": [ { "sellers": [ { "sellerId": "1", "sellerName": "VTEX", "addToCartLink": "", "sellerDefault": true, "commertialOffer": { "AvailableQuantity": 10000, "Price": 197.99, "ListPrice": 197.99, "spotPrice": 197.99, "Tax": 0, "PriceValidUntil": "2025-04-01T13:13:20Z" } } ], "images": [], "itemId": "2000534", "name": "1", "nameComplete": "Top Wood Clock 1", "measurementUnit": "un", "unitMultiplier": 1, "variations": [], "ean": "16001", "modalType": "", "videos": [], "attachments": [], "isKit": false } ], "origin": "intelligent-search" } ], "recordsFiltered": 5, "correction": { "misspelled": false }, "fuzzy": "0", "operator": "and", "translated": false, "pagination": { "count": 1, "current": { "index": 1 }, "before": [], "after": [], "perPage": 24, "next": { "index": 2 }, "previous": { "index": 0 }, "first": { "index": 1 }, "last": { "index": 1 } }, "options": { "sorts": [], "counts": [], "deliveryPromisesEnabled": false }, "searchId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability. Responses containing sponsored products are not cached.", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": 400, "code": "RESOLVER_WARNING", "name": "ResolverWarning", "level": "warn", "response": { "data": "Unsupported sort null" } } } } }, "500": { "description": "Internal Server Error" } } } }, "/facets/{facets}": { "get": { "summary": "List filters for a search", "description": "Lists the possible facets for a given query.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Always read the `Cache-Control` response header at runtime to determine cacheability.\r\n\r\n>ℹ️ **Segment context:** Several parameters on this endpoint replace values previously read from the VTEX segment cookie. See [Migrating from segment](#migrating-from-segment) below.\r\n\r\n## Migrating from segment\r\n\r\nIntelligent Search API (Legacy) reads the following values from the VTEX segment cookie. In v1, pass each one directly as a query parameter:\r\n\r\n| v1 parameter | Segment source |\r\n|:---|:---|\r\n| `locale` | `segment.cultureInfo` |\r\n| `sc` | `segment.channel` |\r\n| `regionId` | `segment.regionId` |\r\n| `country` | `segment.countryCode` or `country` key in `segment.facets` |\r\n| `zip-code` | `zip-code` key in `segment.facets` |\r\n| `coordinates` | `coordinates` key in `segment.facets` |\r\n| `pickupPoint` | `pickupPoint` key in `segment.facets` |\r\n| `deliveryZonesHash` | `deliveryZonesHash` key in `segment.facets` |\r\n| `pickupPointsHash` | `pickupPointsHash` key in `segment.facets` |\r\n\r\nAll other keys in `segment.facets` must be appended to the URL path as `key/value` pairs.\r\n\r\n
\r\nTypeScript reference implementation\r\n\r\nThe following TypeScript snippet shows the full translation:\r\n\r\n```typescript\r\ntype Segment = {\r\n channel?: string | number\r\n regionId?: string\r\n countryCode?: string\r\n cultureInfo?: string\r\n // Semicolon-separated \"key=value\" string, e.g. \"zip-code=22250-040;country=BRA;brand=acme\"\r\n facets?: string\r\n}\r\n\r\nconst SHIPPING_KEYS = new Set([\r\n 'zip-code', 'coordinates', 'country', 'pickupPoint',\r\n 'deliveryZonesHash', 'pickupPointsHash',\r\n])\r\n\r\nfunction segmentToFacetsV1(segment: Segment, query?: string): string {\r\n const shipping: Record = {}\r\n const pathFacets: Array<{ key: string; value: string }> = []\r\n\r\n for (const pair of (segment.facets ?? '').split(';')) {\r\n const eq = pair.indexOf('=')\r\n if (eq < 0) continue\r\n const key = pair.slice(0, eq)\r\n const value = pair.slice(eq + 1)\r\n if (!key || !value) continue\r\n\r\n if (SHIPPING_KEYS.has(key)) {\r\n shipping[key] = value\r\n } else {\r\n pathFacets.push({ key, value })\r\n }\r\n }\r\n\r\n const params: Record = {}\r\n const set = (name: string, value?: string | number) => {\r\n if (value !== undefined && value !== null && value !== '') {\r\n params[name] = String(value)\r\n }\r\n }\r\n\r\n set('sc', segment.channel)\r\n set('locale', segment.cultureInfo)\r\n set('regionId', segment.regionId)\r\n set('country', segment.countryCode ?? shipping.country)\r\n set('zip-code', shipping['zip-code'])\r\n set('coordinates', shipping.coordinates)\r\n set('pickupPoint', shipping.pickupPoint)\r\n set('deliveryZonesHash', shipping.deliveryZonesHash)\r\n set('pickupPointsHash', shipping.pickupPointsHash)\r\n\r\n if (query) params.query = query\r\n\r\n const facetPath = pathFacets.map(f => `${f.key}/${f.value}`).join('/')\r\n const search = new URLSearchParams(params).toString()\r\n\r\n return `https://{accountName}.vtexcommercestable.com.br/api/intelligent-search/v1/facets${facetPath ? `/${facetPath}` : ''}?${search}`\r\n}\r\n```\r\n\r\n
\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "tags": [ "Product list page" ], "parameters": [ { "$ref": "#/components/parameters/facetsPath" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/locale" }, { "$ref": "#/components/parameters/hideUnavailableItems" }, { "in": "query", "name": "removeHiddenFacets", "description": "When `true`, hidden facets are omitted from the response.", "schema": { "type": "boolean", "nullable": true } }, { "$ref": "#/components/parameters/sc" }, { "$ref": "#/components/parameters/regionId" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/zipCode" }, { "$ref": "#/components/parameters/coordinates" }, { "$ref": "#/components/parameters/pickupPoint" }, { "$ref": "#/components/parameters/deliveryZonesHash" }, { "$ref": "#/components/parameters/pickupPointsHash" } ], "responses": { "200": { "description": "OK\r\n\r\nList of facets for the given query.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Facets" }, "example": { "facets": [ { "values": [ { "id": "47", "quantity": 1, "name": "Clothing", "key": "category-2", "value": "clothing", "selected": false, "href": "shirt/blue/clothing?map=ft,color,category" } ], "type": "TEXT", "name": "Category", "hidden": false, "key": "category-2", "quantity": 1 }, { "values": [ { "quantity": 1, "name": "", "key": "price", "selected": false, "range": { "from": 45, "to": 50 } } ], "type": "PRICERANGE", "name": "Price", "hidden": false, "key": "price", "quantity": 1 } ], "sampling": false, "breadcrumb": [ { "name": "shirt", "href": "/shirt?map=ft" } ], "queryArgs": { "query": "shirt", "selectedFacets": [ { "key": "ft", "value": "shirt" } ] }, "translated": false } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } } } } }, "/products": { "get": { "summary": "Get product", "description": "Retrieves a single product by a known identifier. Use this endpoint for product detail pages (PDP) when you have a specific product ID, slug, EAN, SKU ID, or reference.\r\n\r\n>⚠️ Use this endpoint when you need data for one specific product whose identifier is already known (for example, rendering a PDP from a URL slug). Don't use it to fetch multiple products or to run a search query. Use `GET` [Search products](https://developers.vtex.com/docs/api-reference/intelligent-search-api-v1#get-/product-search/-facets-) for those cases. Misusing this endpoint for listings or search bypasses Intelligent Search ranking and impairs the shopper experience.\r\n\r\nWhen called with `field=id` (the default), the product is looked up directly, **skipping the search pipeline**, resulting in lower latency and higher cache-hit likelihood than product search.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Private sales-channel responses are not cached. Always read the `Cache-Control` response header at runtime to determine cacheability.\r\n\r\n>ℹ️ **Segment context:** Several parameters on this endpoint replace values previously read from the VTEX segment cookie. See [Migrating from segment](#migrating-from-segment) below.\r\n\r\n## Migrating from segment\r\n\r\nIntelligent Search API (Legacy) reads the following values from the VTEX segment cookie. In v1, pass each one directly as a query parameter:\r\n\r\n| v1 parameter | Segment source |\r\n|:---|:---|\r\n| `locale` | `segment.cultureInfo` |\r\n| `sc` | `segment.channel` |\r\n| `regionId` | `segment.regionId` |\r\n| `country` | `segment.countryCode` or `country` key in `segment.facets` |\r\n| `zip-code` | `zip-code` key in `segment.facets` |\r\n| `coordinates` | `coordinates` key in `segment.facets` |\r\n| `pickupPoint` | `pickupPoint` key in `segment.facets` |\r\n| `deliveryZonesHash` | `deliveryZonesHash` key in `segment.facets` |\r\n| `pickupPointsHash` | `pickupPointsHash` key in `segment.facets` |\r\n| `utmSource` | `segment.utm_source` |\r\n| `utmCampaign` | `segment.utm_campaign` |\r\n| `utmiCampaign` | `segment.utmi_campaign` |\r\n| `campaigns` | `segment.campaigns` |\r\n| `priceTables` | `segment.priceTables` |\r\n\r\n
\r\nTypeScript reference implementation\r\n\r\nThe following TypeScript snippet shows the full translation:\r\n\r\n```typescript\r\ntype Segment = {\r\n channel?: string | number\r\n regionId?: string\r\n countryCode?: string\r\n cultureInfo?: string\r\n // Semicolon-separated \"key=value\" string, e.g. \"zip-code=22250-040;country=BRA\"\r\n facets?: string\r\n utm_source?: string\r\n utm_campaign?: string\r\n utmi_campaign?: string\r\n campaigns?: string\r\n priceTables?: string\r\n}\r\n\r\nconst SHIPPING_KEYS = new Set([\r\n 'zip-code', 'coordinates', 'country', 'pickupPoint',\r\n 'deliveryZonesHash', 'pickupPointsHash',\r\n])\r\n\r\nfunction segmentToProductsV1(segment: Segment, identifier: string): string {\r\n const shipping: Record = {}\r\n\r\n for (const pair of (segment.facets ?? '').split(';')) {\r\n const eq = pair.indexOf('=')\r\n if (eq < 0) continue\r\n const key = pair.slice(0, eq)\r\n const value = pair.slice(eq + 1)\r\n if (!key || !value) continue\r\n if (SHIPPING_KEYS.has(key)) shipping[key] = value\r\n }\r\n\r\n const params: Record = {}\r\n const set = (name: string, value?: string | number) => {\r\n if (value !== undefined && value !== null && value !== '') {\r\n params[name] = String(value)\r\n }\r\n }\r\n\r\n set('sc', segment.channel)\r\n set('locale', segment.cultureInfo)\r\n set('regionId', segment.regionId)\r\n set('country', segment.countryCode ?? shipping.country)\r\n set('zip-code', shipping['zip-code'])\r\n set('coordinates', shipping.coordinates)\r\n set('pickupPoint', shipping.pickupPoint)\r\n set('deliveryZonesHash', shipping.deliveryZonesHash)\r\n set('pickupPointsHash', shipping.pickupPointsHash)\r\n set('utmSource', segment.utm_source)\r\n set('utmCampaign', segment.utm_campaign)\r\n set('utmiCampaign', segment.utmi_campaign)\r\n set('campaigns', segment.campaigns)\r\n set('priceTables', segment.priceTables)\r\n\r\n params.identifier = identifier\r\n\r\n const search = new URLSearchParams(params).toString()\r\n\r\n return `https://{accountName}.vtexcommercestable.com.br/api/intelligent-search/v1/products?${search}`\r\n}\r\n```\r\n\r\n
\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources) for public sales channels.", "tags": [ "Product details page (PDP)" ], "parameters": [ { "in": "query", "name": "sc", "required": true, "description": "Sales channel (trade policy) ID. Required for this endpoint to resolve pricing and availability. Intelligent Search API (Legacy) previously read this from `segment.channel`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string", "example": "1" } }, { "in": "query", "name": "value", "required": true, "description": "The identifier value to look up, interpreted according to the `field` parameter.", "schema": { "type": "string", "example": "123456" } }, { "in": "query", "name": "field", "description": "Which identifier type `value` represents.\r\n\r\n- `id` (default): product ID. Fastest: skips the search pipeline entirely.\r\n- `slug`: product slug (link text).\r\n- `ean`: SKU EAN.\r\n- `sku`: SKU ID.\r\n- `reference`: SKU reference ID (not the product reference).", "schema": { "type": "string", "enum": [ "id", "slug", "ean", "sku", "reference" ], "default": "id" } }, { "$ref": "#/components/parameters/locale" }, { "$ref": "#/components/parameters/simulationBehavior" }, { "$ref": "#/components/parameters/hideUnavailableItems" }, { "in": "query", "name": "productClusterId", "description": "Restrict to a cluster. Returns `404` if the product is not in this cluster.", "schema": { "type": "string" } }, { "in": "query", "name": "productOriginVtex", "description": "When `true`, returns the product in Catalog (portal) format instead of Intelligent Search format.", "schema": { "type": "boolean" } }, { "in": "query", "name": "show-invisible-items", "description": "When `true`, skips the catalog visibility (`isVisible`) check. Useful for preview and admin flows.", "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/regionId" }, { "$ref": "#/components/parameters/country" }, { "$ref": "#/components/parameters/zipCode" }, { "$ref": "#/components/parameters/coordinates" }, { "$ref": "#/components/parameters/pickupPoint" }, { "$ref": "#/components/parameters/deliveryZonesHash" }, { "$ref": "#/components/parameters/pickupPointsHash" }, { "$ref": "#/components/parameters/utmSource" }, { "$ref": "#/components/parameters/utmCampaign" }, { "$ref": "#/components/parameters/utmiCampaign" }, { "$ref": "#/components/parameters/campaigns" }, { "$ref": "#/components/parameters/priceTables" } ], "responses": { "200": { "description": "OK\r\n\r\nSingle product object. The response is the product itself; there is no `recordsFiltered`, `pagination`, or `searchId` wrapper.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "example": { "productId": "123456", "productName": "Smartphone XYZ", "brand": "TechBrand", "brandId": 9001, "linkText": "smartphone-xyz", "link": "/smartphone-xyz/p", "categories": [ "/Electronics/" ], "categoryId": "10", "categoriesIds": [ "/10/" ], "priceRange": { "sellingPrice": { "highPrice": 999.99, "lowPrice": 999.99 }, "listPrice": { "highPrice": 1299.99, "lowPrice": 1299.99 } }, "specificationGroups": [], "skuSpecifications": [], "productClusters": [], "clusterHighlights": [], "properties": [], "items": [ { "sellers": [ { "sellerId": "1", "sellerDefault": true, "commertialOffer": { "Price": 999.99, "ListPrice": 1299.99, "AvailableQuantity": 50 } } ], "images": [], "itemId": "789", "name": "Smartphone XYZ - 128GB - Black", "nameComplete": "Smartphone XYZ - 128GB - Black", "measurementUnit": "un", "unitMultiplier": 1, "variations": [], "ean": "7891234567890", "modalType": "", "videos": [], "attachments": [], "isKit": false } ], "origin": "intelligent-search" } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request: missing or invalid parameters (for example, missing `sc` or `value`)." }, "401": { "description": "Unauthorized: private sales channel requires valid authentication." }, "403": { "description": "Forbidden: user is not allowed to access this resource." }, "404": { "description": "Not Found: product not found, or not in the requested `productClusterId`." }, "500": { "description": "Internal Server Error" } } } }, "/pickup-point-availability/{facets}": { "get": { "summary": "Get pickup point availability for Delivery Promise", "description": "Retrieves the list of available pickup points with their IDs, distances, addresses, and business hours. This endpoint returns pickup points sorted by distance from the provided coordinates.\r\n\r\n>ℹ️ This endpoint is designed for use in [Delivery Promise for headless stores](https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores) implementations.\r\n\r\n>ℹ️ **Caching:** Responses are cached for public sales channels. Private sales-channel responses are not cached. Always read the `Cache-Control` response header at runtime to determine cacheability.\r\n\r\nYou can call this endpoint in two ways:\r\n\r\n- **With country and ZIP code:** Provide `country` and `zip-code` to retrieve pickup points based on location.\r\n- **With delivery zones and pickup hashes:** Provide pre-computed `deliveryZonesHash` and `pickupPointsHash` for faster lookup.\r\n\r\n>ℹ️ **Segment context:** Several parameters on this endpoint replace values previously read from the VTEX segment cookie. See [Migrating from segment](#migrating-from-segment) below.\r\n\r\n## Migrating from segment\r\n\r\nIntelligent Search API (Legacy) reads the following values from the VTEX segment cookie. In v1, pass each one directly as a query parameter:\r\n\r\n| v1 parameter | Segment source |\r\n|:---|:---|\r\n| `locale` | `segment.cultureInfo` |\r\n| `sc` | `segment.channel` |\r\n| `country` | `segment.countryCode` or `country` key in `segment.facets` |\r\n| `zip-code` | `zip-code` key in `segment.facets` |\r\n| `coordinates` | `coordinates` key in `segment.facets` |\r\n| `pickupPoint` | `pickupPoint` key in `segment.facets` |\r\n| `deliveryZonesHash` | `deliveryZonesHash` key in `segment.facets` |\r\n| `pickupPointsHash` | `pickupPointsHash` key in `segment.facets` |\r\n\r\n
\r\nTypeScript reference implementation\r\n\r\nThe following TypeScript snippet shows the full translation:\r\n\r\n```typescript\r\ntype Segment = {\r\n channel?: string | number\r\n countryCode?: string\r\n cultureInfo?: string\r\n // Semicolon-separated \"key=value\" string, e.g. \"zip-code=22250-040;country=BRA\"\r\n facets?: string\r\n}\r\n\r\nconst SHIPPING_KEYS = new Set([\r\n 'zip-code', 'coordinates', 'country', 'pickupPoint',\r\n 'deliveryZonesHash', 'pickupPointsHash',\r\n])\r\n\r\nfunction segmentToPickupPointAvailabilityV1(segment: Segment): string {\r\n const shipping: Record = {}\r\n\r\n for (const pair of (segment.facets ?? '').split(';')) {\r\n const eq = pair.indexOf('=')\r\n if (eq < 0) continue\r\n const key = pair.slice(0, eq)\r\n const value = pair.slice(eq + 1)\r\n if (!key || !value) continue\r\n if (SHIPPING_KEYS.has(key)) shipping[key] = value\r\n }\r\n\r\n const params: Record = {}\r\n const set = (name: string, value?: string | number) => {\r\n if (value !== undefined && value !== null && value !== '') {\r\n params[name] = String(value)\r\n }\r\n }\r\n\r\n set('sc', segment.channel)\r\n set('locale', segment.cultureInfo)\r\n set('country', segment.countryCode ?? shipping.country)\r\n set('zip-code', shipping['zip-code'])\r\n set('coordinates', shipping.coordinates)\r\n set('pickupPoint', shipping.pickupPoint)\r\n set('deliveryZonesHash', shipping.deliveryZonesHash)\r\n set('pickupPointsHash', shipping.pickupPointsHash)\r\n\r\n const search = new URLSearchParams(params).toString()\r\n\r\n return `https://{accountName}.vtexcommercestable.com.br/api/intelligent-search/v1/pickup-point-availability?${search}`\r\n}\r\n```\r\n\r\n
\r\n\r\n## Permissions\r\n\r\nThis endpoint does not require [authentication](https://developers.vtex.com/docs/guides/authentication) or [permissions](https://help.vtex.com/docs/tutorials/license-manager-resources).", "tags": [ "Delivery Promise" ], "parameters": [ { "$ref": "#/components/parameters/facetsPath" }, { "$ref": "#/components/parameters/query" }, { "$ref": "#/components/parameters/locale" }, { "in": "query", "name": "deliveryZonesHash", "required": false, "description": "Pre-computed hash for delivery zones. Required when using the hashes approach (alternative to country and ZIP code).", "schema": { "type": "string", "example": "4bab2513d897914b0b33f25c8c74f571" } }, { "in": "query", "name": "pickupPointsHash", "required": false, "description": "Pre-computed hash for pickup points. Required when using the hashes approach (alternative to country and ZIP code).", "schema": { "type": "string", "example": "d41d8cd98f00b204e9800998ecf8427e" } }, { "in": "query", "name": "country", "required": false, "description": "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.", "schema": { "type": "string", "example": "USA" } }, { "in": "query", "name": "zip-code", "required": false, "description": "ZIP code or postal code. Required when using the country and ZIP code approach.", "schema": { "type": "string", "example": "10001" } }, { "in": "query", "name": "coordinates", "required": false, "description": "Geographic coordinates in the format `longitude,latitude`. Used to sort results by proximity. Optional: the server derives coordinates from `zip-code` and `country` when not provided.", "schema": { "type": "string", "example": "-43.19532775878906,-22.955032348632812" } }, { "in": "query", "name": "pickupPoint", "required": false, "description": "Pickup point ID to filter results to a specific pickup point.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "description": "Pickup points availability response.", "properties": { "pickupPointDistances": { "type": "array", "description": "List of available pickup points sorted by distance ascending.", "items": { "type": "object", "description": "Pickup point information.", "properties": { "pickupId": { "type": "string", "description": "Unique identifier for the pickup point." }, "pickupName": { "type": "string", "description": "Name of the pickup point." }, "distance": { "type": "number", "description": "Distance from the provided coordinates to the pickup point, in kilometers." }, "isActive": { "type": "boolean", "description": "Indicates whether the pickup point is currently active (`true`) or not (`false`)." }, "address": { "type": "object", "description": "Address details of the pickup point.", "properties": { "street": { "type": "string", "description": "Street name." }, "number": { "type": "string", "description": "Street number." }, "neighborhood": { "type": "string", "description": "Neighborhood." }, "city": { "type": "string", "description": "City." }, "state": { "type": "string", "description": "State or province." }, "postalCode": { "type": "string", "description": "Postal code." } } }, "businessHours": { "type": "array", "description": "Operating hours for each day of the week.", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer", "description": "Day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday).", "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "openingTime": { "type": "string", "description": "Opening time in 24-hour format (HH:MM:SS)." }, "closingTime": { "type": "string", "description": "Closing time in 24-hour format (HH:MM:SS)." } } } } } } } } }, "example": { "pickupPointDistances": [ { "pickupId": "fulfillmentqa_vtexsp", "distance": 4.99, "pickupName": "VTEX SP", "isActive": true, "address": { "city": "New York", "neighborhood": "Manhattan", "number": "350", "postalCode": "10001", "street": "5th Avenue", "state": "NY" }, "businessHours": [ { "dayOfWeek": 1, "openingTime": "09:00:00", "closingTime": "18:00:00" } ] } ] } } }, "headers": { "Cache-Control": { "description": "Indicates whether the response is cacheable. Always read this header at runtime to determine cacheability.", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request: delivery context could not be resolved (neither hashes nor country + ZIP code were usable), or invalid parameters." }, "500": { "description": "Internal Server Error" } } } } }, "components": { "parameters": { "query": { "in": "query", "name": "query", "description": "Search term. It can contain any character.\r\n\r\nThis parameter is named `query` in the API. The short form **`q`** is an alias for `query` and has the same semantics.\r\n\r\nYou can search for products or SKUs using specific ID types by adding search parameters at the end of the store URL:\r\n\r\n- **Single item search:** `?query=[id type]:[id_1]`. Example: `?query=product:98765`\r\n- **Multiple items search:** `?query=[id type]:[id_1];[id_2];[id_3]`. Example: `?query=product:98765;98743`\r\n\r\n>⚠️ All searched IDs should be of the same type.\r\n\r\n## Supported ID types\r\n\r\n| ID Type | Query format | Example |\r\n| - | - | - |\r\n| Product ID | `?query=product:` or `?query=product.id:` | `?query=product:98765` |\r\n| SKU ID | `?query=sku:` or `?query=sku.id:` | `?query=sku.id:12345` |\r\n| Reference ID | `?query=sku.reference:` | `?query=sku.reference:REF123` |\r\n| EAN | `?query=sku.ean:` | `?query=sku.ean:7891234567890` |\r\n| Slug | `?query=product.link:` | `?query=product.link:blue-shirt` |", "schema": { "type": "string", "example": "shirt" } }, "facetsPath": { "in": "path", "name": "facets", "required": true, "description": "## Format\r\n\r\nThe `facets` parameter follows the format: `/${facetKey1}/${facetValue1}/${facetKey2}/${facetValue2}/.../${facetKeyN}/${facetValueN}`.\r\n\r\nThe order in which the terms appear is not relevant to the search.\r\n\r\nYou can also repeat the same `facetKey` several times for different values. For example: `category-1/shoes/color/blue/color/red`.\r\n\r\n## Filter combinations\r\n\r\n- **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.\r\n- **Facets of different types → AND (intersection):** When different facet types are combined, the API returns only products that satisfy all conditions simultaneously.\r\n\r\n## Negative filters (NOT operator)\r\n\r\nTo 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.\r\n\r\n## Available filters\r\n\r\n| `facetKey` | Description | Example |\r\n| - | - | - |\r\n| `trade-policy` *(optional)* | Sales channel filter. Supported for backward compatibility; prefer the `sc` query parameter instead. | `trade-policy/2` |\r\n| `category-${n}` *(optional)* | Filter by category level (1 = department, 2 = category, 3 = subcategory, etc.). | `category-1/clothing/category-2/shirts` |\r\n| `brand` *(optional)* | Filter by brand slug. | `brand/acme` |\r\n| `{specificationName}` *(optional)* | Filter by catalog specification. | `color/blue` |\r\n| `productClusterIds` *(optional)* | Filter by collection ID. | `productClusterIds/262` |\r\n| `price` *(optional)* | Filter by price range `${minPrice}:${maxPrice}`. | `price/100:500` |", "example": "category-1/clothing", "schema": { "nullable": true, "type": "string", "default": "/", "example": "trade-policy/1" } }, "locale": { "in": "query", "name": "locale", "description": "Indicates the target language as a BCP 47 language code. The Intelligent Search must have indexed the account in the target language. Intelligent Search API (Legacy) previously read this from `segment.cultureInfo`. In v1, pass the value directly as a query parameter.", "example": "en-US", "schema": { "type": "string", "nullable": true } }, "simulationBehavior": { "in": "query", "name": "simulationBehavior", "schema": { "type": "string", "enum": [ "default", "skip", "only1P", "only3P", "regionalize1p" ], "nullable": true, "default": "default" }, "description": "Defines the pricing and availability simulation behavior.\r\n\r\n- `default`: Calls the simulation for every single seller.\r\n- `skip`: Never calls the simulation. Use for the fastest response when live pricing is not required.\r\n- `only1P`: Only calls the simulation for first-party sellers.\r\n- `only3P`: Only calls the simulation for third-party sellers.\r\n- `regionalize1p`: Calls regionalized simulation for first-party sellers only." }, "hideUnavailableItems": { "in": "query", "name": "hideUnavailableItems", "description": "Defines whether the result should hide unavailable items (`true`) or not (`false`). When set to `true`, only products with stock are returned.", "schema": { "type": "boolean", "default": false } }, "sc": { "in": "query", "name": "sc", "description": "Sales channel (trade policy) ID. Alternative to including `trade-policy/{id}` in the facets path. Intelligent Search API (Legacy) previously read this from `segment.channel`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string", "example": "1" } }, "regionId": { "in": "query", "name": "regionId", "description": "Region ID for regionalized results. Intelligent Search API (Legacy) previously read this from `segment.regionId`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string" } }, "country": { "in": "query", "name": "country", "description": "Three-letter country code in [ISO 3166 ALPHA-3](https://www.iban.com/country-codes) format. Intelligent Search API (Legacy) previously read this from `segment.countryCode` or the `country` key in `segment.facets`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string", "example": "USA" } }, "zipCode": { "in": "query", "name": "zip-code", "description": "ZIP or postal code. Intelligent Search API (Legacy) previously read this from the `zip-code` key in `segment.facets`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string", "example": "10001" } }, "coordinates": { "in": "query", "name": "coordinates", "description": "Geographic coordinates in the format `longitude,latitude`. Intelligent Search API (Legacy) previously read this from the `coordinates` key in `segment.facets`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string", "example": "-43.19532775878906,-22.955032348632812" } }, "pickupPoint": { "in": "query", "name": "pickupPoint", "description": "Pickup point ID for pickup-in-point delivery context. Intelligent Search API (Legacy) previously read this from the `pickupPoint` key in `segment.facets`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string" } }, "deliveryZonesHash": { "in": "query", "name": "deliveryZonesHash", "description": "Pre-computed delivery zones hash for faster regionalization lookup. Obtain this value from the `POST` [Search delivery zones](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/delivery-zones/_search/v2) endpoint of the Delivery Promise Suggestions API. Intelligent Search API (Legacy) previously read this from the `deliveryZonesHash` key in `segment.facets`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string", "example": "4bab2513d897914b0b33f25c8c74f571" } }, "pickupPointsHash": { "in": "query", "name": "pickupPointsHash", "description": "Pre-computed pickup points hash for faster regionalization lookup. Obtain this value from the `POST` [Search pickup points](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/pickuppoints/_search) endpoint of the Delivery Promise Suggestions API. Intelligent Search API (Legacy) previously read this from the `pickupPointsHash` key in `segment.facets`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string", "example": "d41d8cd98f00b204e9800998ecf8427e" } }, "dpPreview": { "in": "query", "name": "dpPreview", "description": "Previews [Delivery Promise](https://developers.vtex.com/docs/guides/delivery-promise) behavior on accounts still in the `DpReady` activation state, without affecting production search requests. When set to `true`, the response returns `deliveryPromiseEnabled: false`. Once the account is promoted to `DpLive`, remove this parameter, since Delivery Promise is applied in production and the response returns `deliveryPromiseEnabled: true`.", "schema": { "type": "boolean", "example": true } }, "utmSource": { "in": "query", "name": "utmSource", "description": "UTM source value, forwarded to the pricing and availability simulation. Intelligent Search API (Legacy) previously read this from `segment.utm_source`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string" } }, "utmCampaign": { "in": "query", "name": "utmCampaign", "description": "UTM campaign value, forwarded to the pricing and availability simulation. Intelligent Search API (Legacy) previously read this from `segment.utm_campaign`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string" } }, "utmiCampaign": { "in": "query", "name": "utmiCampaign", "description": "UTMi campaign value, forwarded to the pricing and availability simulation. Intelligent Search API (Legacy) previously read this from `segment.utmi_campaign`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string" } }, "campaigns": { "in": "query", "name": "campaigns", "description": "Campaign identifier, forwarded to the pricing and availability simulation. Intelligent Search API (Legacy) previously read this from `segment.campaigns`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string" } }, "priceTables": { "in": "query", "name": "priceTables", "description": "Price table(s) to apply during simulation. Intelligent Search API (Legacy) previously read this from `segment.priceTables`. In v1, pass the value directly as a query parameter.", "schema": { "type": "string" } }, "sponsoredCount": { "in": "query", "name": "sponsoredCount", "description": "Amount of sponsored products to be returned. Applicable only to merchants using [VTEX Ads](https://developers.vtex.com/docs/guides/vtex-ads).", "schema": { "type": "string", "example": "5" } }, "advertisementPlacement": { "in": "query", "name": "advertisementPlacement", "description": "Advertisement placement. Applicable only to merchants using [VTEX Ads](https://developers.vtex.com/docs/guides/vtex-ads).", "schema": { "type": "string", "example": "top_search", "enum": [ "top_search", "middle_search", "search_shelf", "cart_shelf", "plp_shelf", "autocomplete", "homepage" ] } }, "repeatSponsoredProducts": { "in": "query", "name": "repeatSponsoredProducts", "description": "When `true`, the same product can appear as both sponsored and organic. When `false`, sponsored products are removed from the organic list. Applicable only to merchants using [VTEX Ads](https://developers.vtex.com/docs/guides/vtex-ads).", "schema": { "type": "boolean", "example": true } }, "fuzzy": { "in": "query", "name": "fuzzy", "description": "Indicates how the search engine will correct misspelled words by using fuzzy logic. It can be a number representing the max number of misspelled letters, or the string `auto` suggesting that the search engine should set this value by itself.", "schema": { "type": "string" } }, "operator": { "in": "query", "name": "operator", "description": "Indicates how the search engine will deal with the full-text query if there is more than one word. Set `and` if the returned products must have all the words in its metadata, or `or` otherwise.", "schema": { "type": "string", "enum": [ "and", "or" ] } } }, "schemas": { "AutocompleteSearchSuggestions": { "type": "object", "description": "Response body object.", "properties": { "searches": { "type": "array", "description": "List of suggested facets and terms.", "items": { "type": "object", "description": "Suggested facet or term.", "properties": { "term": { "type": "string", "description": "Search term." }, "count": { "type": "number", "description": "Number of times the term was searched." }, "attributes": { "type": "array", "nullable": true, "description": "List of facets in which the term can be searched.", "items": { "type": "object", "description": "Facet information.", "properties": { "key": { "type": "string", "description": "Facet key." }, "value": { "type": "string", "description": "Facet value." }, "labelKey": { "type": "string", "description": "Human-readable format of the facet key." }, "labelValue": { "type": "string", "description": "Human-readable format of the facet value." } } } } } } } } }, "TopSearches": { "type": "object", "description": "Response body object.", "properties": { "searches": { "type": "array", "description": "List of the most searched terms in the past 14 days.", "items": { "type": "object", "description": "Term information.", "properties": { "term": { "type": "string", "description": "Search term." }, "count": { "type": "number", "description": "Number of times the term was searched." } } } } } }, "Correction": { "type": "object", "description": "Response body object.", "properties": { "correction": { "type": "object", "description": "Object that indicates if the term was misspelled and suggests a possible correction.", "properties": { "misspelled": { "type": "boolean", "description": "Defines whether the term was misspelled (`true`) or not (`false`)." }, "correction": { "type": "boolean", "description": "Defines whether the API was able to suggest a correction (`true`) or not (`false`)." }, "text": { "type": "string", "description": "The corrected term. Empty string when there is no correction." }, "highlighted": { "type": "string", "description": "The corrected term with the corrected word highlighted using `` tags. Empty string when there is no correction." } } } } }, "Banners": { "type": "object", "description": "Response body object.", "properties": { "banners": { "type": "array", "description": "List of banners.", "items": { "type": "object", "description": "Banner information.", "properties": { "id": { "type": "string", "description": "Banner ID." }, "name": { "type": "string", "description": "Banner name." }, "area": { "type": "string", "description": "Banner area, which can be a number between 1 and 4, to be used in the store's [Banner](https://developers.vtex.com/docs/guides/vtex-search-banner) block." }, "html": { "type": "string", "description": "Banner HTML, which can be an image or text." } } } } } }, "SearchSuggestions": { "type": "object", "description": "Response body object.", "properties": { "searches": { "type": "array", "description": "List of suggested terms.", "items": { "type": "object", "description": "Suggested term.", "properties": { "term": { "type": "string", "description": "Search term." }, "count": { "type": "number", "description": "Number of times the term was searched." } } } } } }, "ProductSearch": { "type": "object", "description": "Response body object.", "properties": { "products": { "type": "array", "description": "List of active products. Includes any sponsored products when requested.", "items": { "$ref": "#/components/schemas/Product" } }, "recordsFiltered": { "type": "number", "description": "Total number of matching products." }, "correction": { "type": "object", "description": "Present when a spelling correction applies.", "properties": { "misspelled": { "type": "boolean", "description": "Defines whether the search term is misspelled (`true`) or not (`false`)." } } }, "fuzzy": { "type": "string", "description": "Indicates how the search engine corrected the misspelled word by using fuzzy logic." }, "operator": { "type": "string", "enum": [ "and", "or" ], "description": "Indicates how the search engine dealt with the full-text query when there is more than one word." }, "redirect": { "type": "string", "nullable": true, "description": "Redirect URL when the query maps to a configured redirect rule. Present only when a redirect applies." }, "translated": { "type": "boolean", "description": "Defines whether the list of products was translated by Intelligent Search (`true`) or not (`false`)." }, "pagination": { "type": "object", "description": "Pagination information.", "properties": { "count": { "description": "Page count.", "type": "number" }, "current": { "description": "Information about the current page.", "type": "object", "properties": { "index": { "description": "Page index.", "type": "number" } } }, "before": { "description": "Information about the previous pages.", "type": "array", "items": { "type": "object", "properties": { "index": { "description": "Page index.", "type": "number" } } } }, "after": { "description": "Information about the following pages.", "type": "array", "items": { "type": "object", "properties": { "index": { "description": "Page index.", "type": "number" } } } }, "perPage": { "description": "Amount of results per page.", "type": "number" }, "next": { "description": "Information about the next page.", "type": "object", "properties": { "index": { "description": "Page index.", "type": "number" } } }, "previous": { "description": "Information about the previous page.", "type": "object", "properties": { "index": { "description": "Page index.", "type": "number" } } }, "first": { "description": "Information about the first page.", "type": "object", "properties": { "index": { "description": "Page index.", "type": "number" } } }, "last": { "description": "Information about the last page.", "type": "object", "properties": { "index": { "description": "Page index.", "type": "number" } } } } }, "options": { "type": "object", "description": "Search options available for the query.", "properties": { "sorts": { "type": "array", "description": "Available sort options.", "items": { "type": "object", "additionalProperties": true } }, "counts": { "type": "array", "description": "Available product count options.", "items": { "type": "object", "additionalProperties": true } }, "deliveryPromisesEnabled": { "type": "boolean", "description": "Whether Delivery Promise features are enabled for this query." } } }, "searchId": { "type": "string", "description": "Unique identifier for the search session. Use this value when sending search analytics events." } } }, "Product": { "type": "object", "description": "Product information.", "properties": { "cacheId": { "description": "Cache ID.", "type": "string" }, "productId": { "description": "Product unique identifier.", "type": "string" }, "description": { "description": "Product description.", "type": "string" }, "productName": { "description": "Product name.", "type": "string" }, "productReference": { "description": "Product reference code.", "type": "string" }, "linkText": { "description": "Product slug (link text).", "type": "string" }, "brand": { "description": "Brand name.", "type": "string" }, "brandId": { "description": "Brand unique identifier.", "type": "number" }, "link": { "description": "Product URL path in the store.", "type": "string" }, "categories": { "description": "Category paths.", "type": "array", "items": { "description": "Category path.", "type": "string" } }, "categoryId": { "description": "Category unique identifier.", "type": "string" }, "categoriesIds": { "description": "List of category IDs in the corresponding category path.", "type": "array", "items": { "description": "Category ID.", "type": "string" } }, "priceRange": { "description": "Price range information.", "type": "object", "properties": { "sellingPrice": { "description": "Selling price range.", "type": "object", "properties": { "highPrice": { "description": "Highest selling price.", "type": "number" }, "lowPrice": { "description": "Lowest selling price.", "type": "number" } } }, "listPrice": { "description": "List price range.", "type": "object", "properties": { "highPrice": { "description": "Highest list price.", "type": "number" }, "lowPrice": { "description": "Lowest list price.", "type": "number" } } } } }, "specificationGroups": { "description": "Specification groups information.", "type": "array", "items": { "type": "object", "description": "Specification group information.", "properties": { "originalName": { "description": "Specification group original name.", "type": "string" }, "name": { "description": "Specification group name.", "type": "string" }, "specifications": { "description": "List of specifications.", "type": "array", "items": { "type": "object", "description": "Specification information.", "properties": { "originalName": { "description": "Specification original name.", "type": "string" }, "name": { "description": "Specification name.", "type": "string" }, "values": { "description": "Specification values.", "type": "array", "items": { "type": "string" } } } } } } } }, "skuSpecifications": { "description": "SKU specifications.", "type": "array", "items": { "type": "object", "description": "SKU specification information.", "properties": { "field": { "type": "object", "description": "SKU specification field.", "properties": { "name": { "type": "string", "description": "SKU specification field name." }, "originalName": { "type": "string", "description": "SKU specification field original name." } } }, "values": { "type": "array", "description": "SKU specification field values.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "SKU specification value name." }, "originalName": { "type": "string", "description": "SKU specification value original name." } } } } } } }, "productClusters": { "description": "Product clusters (collections) the product belongs to.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cluster unique identifier." }, "name": { "type": "string", "description": "Cluster name." } } } }, "clusterHighlights": { "description": "Cluster highlights information.", "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Cluster unique identifier." }, "name": { "type": "string", "description": "Cluster name." } } } }, "properties": { "description": "Product properties.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Property name." }, "originalName": { "type": "string", "description": "Property original name." }, "values": { "type": "array", "items": { "type": "string", "description": "Property value." } } } } }, "items": { "description": "Information about the related SKUs.", "type": "array", "items": { "type": "object", "description": "SKU information.", "additionalProperties": true, "properties": { "sellers": { "description": "List of sellers.", "type": "array", "items": { "type": "object", "description": "Seller information.", "properties": { "sellerId": { "description": "Seller unique identifier.", "type": "string" }, "sellerName": { "description": "Seller name.", "type": "string" }, "addToCartLink": { "description": "Add to cart link.", "type": "string" }, "sellerDefault": { "description": "Whether this is the default seller.", "type": "boolean" }, "commertialOffer": { "description": "Commercial offer information.", "type": "object", "properties": { "DeliverySlaSamplesPerRegion": { "description": "Delivery SLA samples per region.", "type": "object", "additionalProperties": true }, "DeliverySlaSamples": { "description": "Delivery SLA samples.", "type": "array", "items": { "type": "object", "additionalProperties": true } }, "AvailableQuantity": { "description": "Indicates availability. `10000` means available; `0` means unavailable.", "type": "number" }, "discountHighlights": { "description": "Discount highlights.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Discount highlight name." } } } }, "Installments": { "description": "Installments information.", "type": "array", "items": { "type": "object", "properties": { "PaymentSystemName": { "type": "string", "description": "Payment system name." }, "Value": { "type": "number", "description": "Installment value." }, "InterestRate": { "type": "number", "description": "Interest rate." }, "TotalValuePlusInterestRate": { "type": "number", "description": "Total value plus interest rate." }, "NumberOfInstallments": { "type": "number", "description": "Number of installments." }, "Name": { "type": "string", "description": "Payment condition name." }, "PaymentSystemGroupName": { "type": "string", "description": "Payment system group." } } } }, "Price": { "description": "Price of the item.", "type": "number" }, "ListPrice": { "description": "List price of the item.", "type": "number" }, "spotPrice": { "description": "Special promotional price available under specific conditions, such as a discount for a specific payment method. May differ from `Price`.", "type": "number" }, "taxPercentage": { "description": "Tax percentage.", "type": "number" }, "PriceWithoutDiscount": { "description": "Price without discount.", "type": "number" }, "Tax": { "description": "Tax value.", "type": "number" }, "GiftSkuIds": { "description": "List of gift SKU IDs.", "type": "array", "items": { "type": "string" } }, "BuyTogether": { "description": "IDs of items that can be bought together with this item.", "type": "array", "items": { "type": "string" } }, "RewardValue": { "description": "Credit the customer receives when finalizing an order that includes this SKU.", "type": "number" }, "PriceValidUntil": { "description": "Date until the price is valid, in ISO 8601 format.", "type": "string" }, "GetInfoErrorMessage": { "description": "Get info error message.", "type": "string", "nullable": true }, "CacheVersionUsedToCallCheckout": { "description": "Cache version used to call Checkout.", "type": "string" }, "teasers": { "description": "Promotion teasers.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Promotion name." }, "conditions": { "type": "object", "description": "Conditions for the promotion to be valid.", "properties": { "minimumQuantity": { "type": "number", "description": "Minimum quantity of the item." }, "parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } } } }, "effects": { "type": "object", "description": "Promotion effects.", "properties": { "parameters": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "value": { "type": "string" } } } } } } } } } } } } } }, "images": { "description": "SKU images.", "type": "array", "items": { "type": "object", "properties": { "imageId": { "type": "string", "description": "Image unique identifier." }, "cacheId": { "type": "string", "description": "Cache ID." }, "imageTag": { "type": "string", "description": "HTML tag for the selected image." }, "imageLabel": { "type": "string", "description": "Image label." }, "imageText": { "type": "string", "description": "Image text (alt text)." }, "imageUrl": { "type": "string", "description": "Image URL." } } } }, "itemId": { "description": "SKU unique identifier.", "type": "string" }, "name": { "description": "SKU name.", "type": "string" }, "nameComplete": { "description": "Combination of the product name and the SKU name.", "type": "string" }, "complementName": { "description": "Complement name.", "type": "string" }, "referenceId": { "description": "SKU alternate IDs.", "type": "array", "items": { "type": "object", "properties": { "Key": { "type": "string", "description": "Alternate ID key." }, "Value": { "type": "string", "description": "Alternate ID value." } } } }, "measurementUnit": { "description": "Measurement unit.", "type": "string" }, "unitMultiplier": { "description": "Unit multiplier. If the multiplier is 5.0000, the product can be added in multiples of 5.", "type": "number" }, "variations": { "description": "Variations.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Variation name." }, "values": { "type": "array", "items": { "type": "string" } } } } }, "ean": { "description": "EAN value.", "type": "string" }, "modalType": { "description": "Links an unusual type of SKU to a carrier specialized in delivering it (e.g. `\"Refrigerated products\"`). See [How the modal works](https://help.vtex.com/en/tutorial/how-does-the-modal-work--tutorials_125).", "type": "string" }, "videos": { "description": "SKU videos.", "type": "array", "items": { "type": "string", "description": "Video URL." } }, "attachments": { "description": "Attachments related to the SKU.", "type": "array", "items": { "type": "object", "description": "Attachment information.", "properties": { "id": { "type": "number", "description": "Attachment unique identifier." }, "name": { "type": "string", "description": "Attachment name." }, "schema": { "type": "object", "description": "Free-form JSON schema describing the attachment.", "additionalProperties": true }, "fields": { "type": "array", "description": "Attachment fields.", "items": { "type": "object", "properties": { "field_name": { "type": "string", "description": "Field name." }, "max_characters": { "type": "string", "description": "Maximum number of characters allowed for the field." }, "domain_values": { "type": "string", "description": "Allowed values for the field." } } } }, "isActive": { "type": "boolean", "description": "Whether the attachment is active." }, "isRequired": { "type": "boolean", "description": "Whether the attachment is required." } } } }, "isKit": { "description": "Defines whether the SKU is a kit (`true`) or not (`false`).", "type": "boolean" }, "kitItems": { "description": "SKUs that compose the kit. Returned when `isKit` is `true`.", "type": "array", "nullable": true, "items": { "type": "object", "properties": { "itemId": { "type": "string", "description": "Component SKU ID." }, "amount": { "type": "number", "description": "Quantity of the component SKU per kit." } } } }, "estimatedDateArrival": { "description": "Estimated arrival date for the SKU, when configured.", "type": "string", "nullable": true } } } }, "releaseDate": { "description": "Release date.", "type": "number" }, "origin": { "description": "Origin of the product in the trade policy.", "type": "string" } } }, "Facets": { "type": "object", "description": "Response body object.", "properties": { "facets": { "type": "array", "description": "List of facets.", "items": { "type": "object", "description": "Facet information.", "properties": { "values": { "type": "array", "description": "Possible values.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Value ID." }, "quantity": { "type": "number", "description": "Number of resulting products." }, "name": { "type": "string", "description": "Human-readable format of the facet value." }, "key": { "type": "string", "description": "Facet key." }, "value": { "type": "string", "description": "Facet value." }, "selected": { "type": "boolean", "description": "Defines whether the value is selected (`true`) or not (`false`)." }, "href": { "type": "string", "description": "Query URL." } } } }, "type": { "type": "string", "description": "Facet type, which can be:\r\n\r\n- `TEXT`: The value is a simple text.\r\n- `PRICERANGE`: The value contains the property `range` representing the minimum and the maximum price for the query.\r\n- `DELIVERY`: The value represents a delivery option. Only appears in searches using [Delivery Promise](https://help.vtex.com/docs/tutorials/delivery-promise-beta).", "enum": [ "TEXT", "PRICERANGE", "DELIVERY" ] }, "name": { "type": "string", "description": "Human-readable format of the facet key." }, "hidden": { "type": "boolean", "description": "Defines whether the client-side should hide the facet (`true`) or not (`false`)." }, "key": { "type": "string", "description": "Facet key." }, "quantity": { "type": "number", "description": "Number of possible values." } } } }, "sampling": { "type": "boolean", "description": "Indicates whether there was sampling in the aggregation of facets. In search results with many products, only the first 30000 are aggregated to avoid performance issues." }, "breadcrumb": { "type": "array", "description": "Generated breadcrumb for the given query.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Breadcrumb label." }, "href": { "type": "string", "description": "Breadcrumb link." } } } }, "queryArgs": { "type": "object", "description": "Term and facets used in the query.", "properties": { "query": { "type": "string", "description": "Search term used in the query." }, "selectedFacets": { "type": "array", "description": "Facets used in the query.", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Facet key." }, "value": { "type": "string", "description": "Facet value." } } } } } }, "translated": { "type": "boolean", "description": "Defines whether the facets were translated by Intelligent Search (`true`) or not (`false`)." } } }, "ErrorResponse": { "type": "object", "description": "Error response information.", "properties": { "status": { "type": "integer", "description": "HTTP status code." }, "code": { "type": "string", "description": "Error code." }, "name": { "type": "string", "description": "Error name." }, "level": { "type": "string", "description": "Error severity level." }, "response": { "type": "object", "description": "Response details.", "properties": { "data": { "type": "string", "description": "Error response message." } } } } } } }, "tags": [ { "name": "Autocomplete" }, { "name": "Product list page" }, { "name": "Product details page (PDP)" }, { "name": "Delivery Promise" } ] }