{ "openapi": "3.0.0", "info": { "title": "Delivery Promise Suggestions API", "description": "The Delivery Promise Suggestions API provides real-time suggestions for delivery and pickup options based on product availability, user location, and fulfillment context for stores that use [Delivery Promise](https://help.vtex.com/docs/tutorials/delivery-promise-beta) and [Delivery Options](https://help.vtex.com/en/docs/tutorials/delivery-options-beta). It helps optimize the customer shopping experience by suggesting the best fulfillment options for each product. \r\n\r\n>ℹ️ This API is in beta, which means that we are working to improve it. If you have any questions, please contact our [Support Center](https://support.vtex.com/hc/en-us/requests).", "contact": {}, "version": "1.0" }, "servers": [ { "url": "https://{accountName}.{environment}.com.br", "description": "VTEX server URL.", "variables": { "accountName": { "description": "Name of the VTEX account. Used as part of the URL.", "default": "apiexamples" }, "environment": { "description": "Environment to use. Used as part of the URL.", "enum": [ "vtexcommercestable" ], "default": "vtexcommercestable" } } } ], "paths": { "/api/logistics-shipping/zones/_search": { "post": { "tags": [ "Logistics shipping" ], "summary": "Get delivery zones and pickup points hashes", "description": "Retrieves the delivery zones and the pickup points available for a given location, based on postal code, geographic coordinates, and country. This endpoint returns both the delivery zones hash (`deliveryZonesHash`) and the pickup points hash (`pickupPointsHash`) in a single response.\r\n\r\nBoth hashes represent the shopper's fulfillment context and are used by the [Get delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#get-/api/delivery-promise-suggestions) and [Search delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/delivery-promise-suggestions/_search) endpoints, as well as by the [Intelligent Search API](https://developers.vtex.com/docs/api-reference/intelligent-search-api) endpoints. In the delivery suggestions endpoints, `deliveryZonesHash` is required and `pickupPointsHash` (sent as `pickupsHash`) is optional.\r\n\r\n>ℹ️ This is the recommended endpoint for generating the fulfillment context hashes. It replaces the [Search delivery zones](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/delivery-zones/_search/v2) and [Search pickup points](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/pickuppoints/_search) endpoints, which are deprecated.\r\n\r\n## Hash expiration\r\n\r\nBoth hashes returned by this endpoint have a time to live (TTL) of 30 minutes. After this period, they expire and are no longer valid for use in the Delivery Promise Suggestions API and the Intelligent Search API. Requests sent with an expired hash may be rejected or return invalid responses.\r\n\r\nTo generate new hashes, call this endpoint again. There is no penalty or side effect in regenerating them. We recommend that integrations relying on these hashes call this endpoint as close as possible to the moment the hashes are used, and handle the expired hash scenario by requesting new ones.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a `403` status code. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Logistics | Logistics access | **Logistics full access** |\r\n| Logistics | Logistics access | **Logistics shipping full access** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--sjGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Logistics - Full access | Logistics full access |\r\n| Logistics - Full access | Logistics shipping full access |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZonesSearchRequest" }, "example": { "country": "BRA", "zipCode": "24230220", "coordinate": { "longitude": -43.10804748535156, "latitude": -22.910741806030273 } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ZonesResponse" }, "example": { "deliveryZoneIds": [ "BRA_COUNTRY", "BRA_REGION_SUDESTE", "BRA_STATE_RJ", "BRA_SUBSTATE_RJ_REG_METROPOLITANA", "apiexamples_1", "apiexamplespickup_1147da1", "apiexamplespickup_12ebfe9", "apiexamplespickup_188f2ec", "apiexamplespickup_1961f19", "apiexamplespickup_1d4c9fe", "apiexamplespickup_Goytacazes", "apiexamplespickup_Itaborai2", "apiexamplespickup_Sapucaia2" ], "deliveryZonesHash": "6513033aa7857d8e10056b68b86eacc7", "pickupPointsHash": "1e17390379ef93fe2b242483e5f80760", "pickupDistances": [ { "pickupId": "apiexamplespickup_2", "distance": 25.03369140625, "pickupName": "Pickup | Rio de Janeiro - Irajá (Passeio store)" }, { "pickupId": "apiexamplespickup_1", "distance": 25.228069305419922, "pickupName": "Pickup | Rio de Janeiro - Irajá (Truck store)" }, { "pickupId": "apiexamplespickup_3", "distance": 28.024667739868164, "pickupName": "Pickup | Itaboraí - São Joaquim" }, { "pickupId": "apiexamplespickup_7", "distance": 60.680458068847656, "pickupName": "Pickup | Rio de Janeiro - Santa Cruz" } ] } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "deprecated": false } }, "/api/logistics-shipping/delivery-zones/_search/v2": { "post": { "tags": [ "Logistics shipping" ], "summary": "Search delivery zones", "description": ">⚠️ This endpoint is deprecated. Use the [Get delivery zones and pickup points hashes](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/zones/_search) endpoint instead, which returns both the delivery zones hash and the pickup points hash in a single response. This endpoint still works, but its use is no longer recommended.\r\n\r\nRetrieves available delivery zones based on location information. This endpoint helps determine which delivery zones are applicable for a given address, using postal code, geographic coordinates, and country.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a `403` status code. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Logistics | Logistics access | **Logistics full access** |\r\n| Logistics | Logistics access | **Logistics shipping full access** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--sjGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Logistics - Full access | Logistics full access |\r\n| Logistics - Full access | Logistics shipping full access |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryZonesSearchRequest" }, "example": { "zipCode": "04538132", "coordinate": { "latitude": -23.590057, "longitude": -46.682033 }, "country": "BRA" } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryZonesResponse" }, "example": { "deliveryZoneIds": [ "BRA_COUNTRY", "BRA_REGION_NORDESTE", "BRA_SUBSTATE_PB_INTERIOR" ], "deliveryZonesHash": "c3e1a42f7b9d4e81aafe24ba6e7b120f", "countryCode": "BRA" } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "deprecated": true } }, "/api/logistics-shipping/pickuppoints/_search": { "post": { "tags": [ "Logistics shipping" ], "summary": "Search pickup points", "description": ">⚠️ This endpoint is deprecated. Use the [Get delivery zones and pickup points hashes](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/zones/_search) endpoint instead, which returns both the delivery zones hash and the pickup points hash in a single response. This endpoint still works, but its use is no longer recommended.\r\n\r\nRetrieves available pickup points based on location information and distance constraints. This endpoint helps find pickup locations near a given address, using postal code, geographic coordinates, country, and optional maximum distance.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise they will receive a status code `403` error. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Logistics | Logistics access | **Logistics full access** |\r\n| Logistics | Logistics access | **Logistics shipping full access** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--sjGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Logistics - Full access | Logistics full access |\r\n| Logistics - Full access | Logistics shipping full access |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "maxDistance", "in": "query", "description": "Maximum distance in kilometers from the specified location to search for pickup points.", "required": false, "style": "form", "schema": { "type": "number", "example": 10 } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickupPointsSearchRequest" }, "example": { "zipCode": "01310930", "country": "BRA", "coordinate": { "latitude": -23.555404663085938, "longitude": -46.6456413269043 } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PickupPointsResponse" }, "example": { "pickupPointDistances": [ { "pickupId": "fulfillmentqa_vtexsp", "distance": 4.990988731384277, "pickupName": "VTEX SP", "isActive": true, "address": { "city": "São Paulo", "neighborhood": "Itaim Bibi", "number": "4440", "postalCode": "04538-132", "street": "Avenida Brigadeiro Faria Lima", "state": "SP" }, "businessHours": [ { "dayOfWeek": 0, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 1, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 2, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 3, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 4, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 5, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 6, "openingTime": "00:00:00", "closingTime": "23:59:00" } ] }, { "pickupId": "fulfillmentqa1_vtex-sp", "distance": 5.6930670738220215, "pickupName": "VTEX SP", "isActive": true, "address": { "city": "São Paulo", "neighborhood": "Itaim Bibi", "number": "4440", "postalCode": "04538-132", "street": "Avenida Brigadeiro Faria Lima", "state": "SP" }, "businessHours": [ { "dayOfWeek": 0, "openingTime": "00:00:00", "closingTime": "00:00:00" }, { "dayOfWeek": 1, "openingTime": "00:00:00", "closingTime": "00:00:00" }, { "dayOfWeek": 2, "openingTime": "00:00:00", "closingTime": "00:00:00" }, { "dayOfWeek": 3, "openingTime": "00:00:00", "closingTime": "00:00:00" }, { "dayOfWeek": 4, "openingTime": "00:00:00", "closingTime": "00:00:00" }, { "dayOfWeek": 5, "openingTime": "00:00:00", "closingTime": "00:00:00" }, { "dayOfWeek": 6, "openingTime": "00:00:00", "closingTime": "00:00:00" } ] }, { "pickupId": "fulfillmentqa1_c5bc07a6-389b-4366-bf95-bdb841ebcdda", "distance": 6.2001118659973145, "pickupName": "VTEX Vila Olimpia", "isActive": true, "address": { "city": "São Paulo", "neighborhood": "Vila Olímpia", "number": "s/n", "postalCode": "04551-080", "street": "Rua São Tomé", "state": "SP" }, "businessHours": [ { "dayOfWeek": 0, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 1, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 2, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 3, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 4, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 5, "openingTime": "00:00:00", "closingTime": "23:59:00" }, { "dayOfWeek": 6, "openingTime": "00:00:00", "closingTime": "23:59:00" } ] } ], "pickupPointsHash": "b92e64d0a08f4c6785e6d0319cbad19a" } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "deprecated": true } }, "/api/delivery-promise-suggestions/_search": { "post": { "tags": [ "Delivery suggestions" ], "summary": "Search delivery suggestions", "description": "Retrieves delivery and pickup suggestions for a batch of products. The response contains suggestions for each requested product, including [available delivery and pickup options](https://help.vtex.com/docs/tutorials/delivery-options-beta#creating-delivery-options) with timing information and selection criteria tags (e.g., fastest, nearest).\r\n\r\n>⚠️ The `deliveryZonesHash` and `pickupsHash` values expire 30 minutes after being generated. Requests sent with an expired hash may be rejected or return invalid responses. To get new hashes, call the [Get delivery zones and pickup points hashes](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/zones/_search) endpoint again. There is no penalty or side effect in regenerating them, so we recommend generating the hashes as close as possible to the moment they are used.\r\n\r\n## Hash combinations\r\n\r\nThe `deliveryZonesHash` field is required in every request. The `pickupsHash` field is optional. If you send it, send it together with the required `deliveryZonesHash`. The table below shows the valid combinations:\r\n\r\n| **`deliveryZonesHash`** | **`pickupsHash`** | **Valid** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Sent | Not sent | ✅ Yes |\r\n| Sent | Sent | ✅ Yes |\r\n| Not sent | Sent | ❌ No |\r\n| Not sent | Not sent | ❌ No |\r\n\r\nSee the request body examples for each valid combination.\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a `403` status code. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Logistics | Logistics access | **Logistics full access** |\r\n| Logistics | Logistics access | **Logistics shipping full access** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--sjGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Logistics - Full access | Logistics full access |\r\n| Logistics - Full access | Logistics shipping full access |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverySuggestionRequest" }, "examples": { "deliveryAndPickup": { "summary": "With deliveryZonesHash and pickupsHash", "value": { "products": [ { "productId": "123", "itemId": "123-1" }, { "productId": "456", "itemId": "456-1" } ], "deliveryZonesHash": "abc123def456", "pickupsHash": "xyz789uvw012" } }, "deliveryOnly": { "summary": "With only deliveryZonesHash", "value": { "products": [ { "productId": "123", "itemId": "123-1" }, { "productId": "456", "itemId": "456-1" } ], "deliveryZonesHash": "abc123def456" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverySuggestionResponse" }, "example": { "suggestions": [ { "productId": "123", "suggestions": { "delivery": [ { "id": "express-delivery", "name": "Express Delivery", "slaTimeTarget": { "from": 0, "to": 4, "unit": "h" }, "conditions": [ "fastest" ] }, { "id": "standard-delivery", "name": "Standard Delivery", "slaTimeTarget": { "from": 1, "to": 3, "unit": "d" }, "conditions": [] } ], "pickup": [ { "id": "store-downtown", "name": "Downtown Store", "slaTimeTarget": { "from": 0, "to": 2, "unit": "h" }, "conditions": [ "nearest" ] } ] } }, { "productId": "456", "itemId": "456-1", "suggestions": { "delivery": [ { "id": "standard-delivery", "name": "Standard Delivery", "slaTimeTarget": { "from": 2, "to": 5, "unit": "d" }, "conditions": [ "fastest" ] } ], "pickup": [] } } ] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "The products array cannot be empty.": { "value": { "message": "The products array cannot be empty." } }, "The maximum number of products allowed is 20.": { "value": { "message": "The maximum number of products allowed is 20." } }, "The product list cannot be empty.": { "value": { "message": "The product list cannot be empty." } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Invalid or missing authentication credentials." } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Request origin not allowed." } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Request limit exceeded. Please try again later." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "An unexpected error occurred on the server." } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "deprecated": false } }, "/api/delivery-promise-suggestions": { "get": { "tags": [ "Delivery suggestions" ], "summary": "Get delivery suggestions", "description": "Retrieves delivery and pickup suggestions for products using query parameters. This method supports caching, bookmarking, and browser optimizations. The response contains suggestions for each requested product, including [available delivery and pickup options](https://help.vtex.com/docs/tutorials/delivery-options-beta#creating-delivery-options) with timing information and selection criteria tags (e.g., fastest, nearest).\r\n\r\n>⚠️ The `deliveryZonesHash` and `pickupsHash` values expire 30 minutes after being generated. Requests sent with an expired hash may be rejected or return invalid responses. To get new hashes, call the [Get delivery zones and pickup points hashes](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/zones/_search) endpoint again. There is no penalty or side effect in regenerating them, so we recommend generating the hashes as close as possible to the moment they are used.\r\n\r\n## Hash combinations\r\n\r\nThe `deliveryZonesHash` parameter is required in every request. The `pickupsHash` parameter is optional. If you send it, send it together with the required `deliveryZonesHash`. The table below shows the valid combinations:\r\n\r\n| **`deliveryZonesHash`** | **`pickupsHash`** | **Valid** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Sent | Not sent | ✅ Yes |\r\n| Sent | Sent | ✅ Yes |\r\n| Not sent | Sent | ❌ No |\r\n| Not sent | Not sent | ❌ No |\r\n\r\nExample with only `deliveryZonesHash`:\r\n\r\n```\r\nGET /api/delivery-promise-suggestions?products[0].productId=123&deliveryZonesHash=abc123def456\r\n```\r\n\r\nExample with `deliveryZonesHash` and `pickupsHash`:\r\n\r\n```\r\nGET /api/delivery-promise-suggestions?products[0].productId=123&deliveryZonesHash=abc123def456&pickupsHash=xyz789uvw012\r\n```\r\n\r\n## Permissions\r\n\r\nAny user or [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys) must have at least one of the appropriate [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3) to be able to successfully run this request. Otherwise, they will receive a `403` status code. These are the applicable resources for this endpoint:\r\n\r\n| **Product** | **Category** | **Resource** |\r\n| --------------- | ----------------- | ----------------- |\r\n| Logistics | Logistics access | **Logistics viewer** |\r\n\r\nYou can [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) with that resource or use one of the following [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy):\r\n\r\n| **Role** | **Resource** | \r\n| --------------- | ----------------- | \r\n| Logistics - Read only | Logistics viewer |\r\n\r\n>❗ Assigning a [predefined role](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) to users or API keys usually grants permission to multiple [License Manager resources](https://help.vtex.com/en/tutorial/license-manager-resources--3q6ztrC8YynQf6rdc6euk3). If some of these permissions are not necessary, consider creating a custom role instead. For more information regarding security, see [Best practices for using API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm).\r\n\r\nTo learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).", "parameters": [ { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" }, { "name": "products[0].productId", "in": "query", "description": "The unique identifier of the first product. Use index notation for multiple products (e.g., `products[0].productId`, `products[1].productId`).", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "123" } }, { "name": "products[0].itemId", "in": "query", "description": "The specific SKU ID for the first product. If omitted, all SKUs for the product are evaluated. Use index notation for multiple SKUs (e.g., `products[0].itemId`, `products[1].itemId`).", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "123-1" } }, { "name": "deliveryZonesHash", "in": "query", "description": "Hash representing the user's delivery context, which is a part of the fulfillment context. This hash is generated by the [Get delivery zones and pickup points hashes](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/zones/_search) endpoint and expires 30 minutes after being generated. This parameter is required in every request, including requests that send `pickupsHash`.", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "abc123def456" } }, { "name": "pickupsHash", "in": "query", "description": "Hash representing the user's pickup context, which is a part of the fulfillment context. This hash corresponds to the `pickupPointsHash` field returned by the [Get delivery zones and pickup points hashes](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/zones/_search) endpoint and expires 30 minutes after being generated. This parameter is optional. If you send it, send it together with the required `deliveryZonesHash`.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "xyz789uvw012" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliverySuggestionResponse" }, "example": { "suggestions": [ { "productId": "123", "suggestions": { "delivery": [ { "id": "express-delivery", "name": "Express Delivery", "slaTimeTarget": { "from": 0, "to": 4, "unit": "h" }, "conditions": [ "fastest" ] }, { "id": "standard-delivery", "name": "Standard Delivery", "slaTimeTarget": { "from": 1, "to": 3, "unit": "d" }, "conditions": [] } ], "pickup": [ { "id": "store-downtown", "name": "Downtown Store", "slaTimeTarget": { "from": 0, "to": 2, "unit": "h" }, "conditions": [ "nearest" ] } ] } }, { "productId": "456", "itemId": "456-1", "suggestions": { "delivery": [ { "id": "standard-delivery", "name": "Standard Delivery", "slaTimeTarget": { "from": 2, "to": 5, "unit": "d" }, "conditions": [ "fastest" ] } ], "pickup": [] } } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "Unauthorized", "message": "Invalid or missing authentication credentials." } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "RateLimitExceeded", "message": "Request limit exceeded. Please try again later." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "code": "InternalError", "message": "An unexpected error occurred on the server." } } } } }, "security": [ { "appKey": [], "appToken": [] }, { "VtexIdclientAutCookie": [] } ], "deprecated": false } } }, "components": { "parameters": { "Content-Type": { "name": "Content-Type", "in": "header", "description": "Type of the content being sent.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } }, "Accept": { "name": "Accept", "in": "header", "description": "HTTP Client Negotiation _Accept_ Header. Indicates the types of responses the client can understand.", "required": true, "style": "simple", "schema": { "type": "string", "default": "application/json" } } }, "schemas": { "ZonesSearchRequest": { "type": "object", "description": "Request body for delivery zones and pickup points search queries.", "required": [ "zipCode", "coordinate", "country" ], "properties": { "zipCode": { "type": "string", "description": "Postal code of the location." }, "coordinate": { "type": "object", "description": "Geographic coordinates of the location, used to calculate the distance to the available pickup points.", "properties": { "latitude": { "type": "number", "description": "Latitude of the location." }, "longitude": { "type": "number", "description": "Longitude of the location." } } }, "country": { "type": "string", "description": "Three-letter country code (ISO 3166-1 alpha-3)." } } }, "ZonesResponse": { "type": "object", "description": "Response containing the delivery zones and the pickup points available for the specified location, along with the hashes that represent the fulfillment context.", "properties": { "deliveryZoneIds": { "type": "array", "description": "Array of delivery zones available for the location.", "items": { "type": "string", "description": "Unique identifier of the delivery zone." } }, "deliveryZonesHash": { "type": "string", "description": "Hash representing the delivery zones context. This hash is required in the `deliveryZonesHash` field of the [Get delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#get-/api/delivery-promise-suggestions) and the [Search delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/delivery-promise-suggestions/_search) endpoints. It expires 30 minutes after being generated." }, "pickupPointsHash": { "type": "string", "description": "Hash representing the pickup points context. This hash can be sent in the optional `pickupsHash` field of the [Get delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#get-/api/delivery-promise-suggestions) and the [Search delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/delivery-promise-suggestions/_search) endpoints. It expires 30 minutes after being generated." }, "pickupDistances": { "type": "array", "description": "Array of pickup points available near the location.", "items": { "type": "object", "description": "Pickup point information.", "properties": { "pickupId": { "type": "string", "description": "Unique identifier of the pickup point." }, "distance": { "type": "number", "description": "Distance from the searched location in kilometers." }, "pickupName": { "type": "string", "description": "Human-readable name of the pickup point." } } } } } }, "DeliveryZonesSearchRequest": { "type": "object", "description": "Request body for delivery zones search queries.", "required": [ "zipCode", "country" ], "properties": { "zipCode": { "type": "string", "description": "Postal code of the location." }, "coordinate": { "type": "object", "description": "Geographic coordinates.", "properties": { "latitude": { "type": "number", "description": "Latitude of the location." }, "longitude": { "type": "number", "description": "Longitude of the location." } } }, "country": { "type": "string", "description": "Three-letter country code (ISO 3166-1 alpha-3)." } } }, "PickupPointsSearchRequest": { "type": "object", "description": "Request body for location-based search queries.", "required": [ "zipCode", "coordinate", "country" ], "properties": { "zipCode": { "type": "string", "description": "Postal code of the location." }, "coordinate": { "type": "object", "description": "Geographic coordinates.", "properties": { "latitude": { "type": "number", "description": "Latitude of the location." }, "longitude": { "type": "number", "description": "Longitude of the location." } } }, "country": { "type": "string", "description": "Three-letter country code (ISO 3166-1 alpha-3)." } } }, "DeliveryZonesResponse": { "type": "object", "description": "Response containing available delivery zones for the specified location.", "properties": { "deliveryZonesIds": { "type": "array", "description": "Array of delivery zones available for the location.", "items": { "type": "string", "description": "Unique identifier of the delivery zone." } }, "deliveryZonesHash": { "type": "string", "description": "Hash representing the delivery zones context. This hash is required in the [Get delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#get-/api/delivery-promise-suggestions) and the [Search delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/delivery-promise-suggestions/_search) endpoints." }, "countryCode": { "type": "string", "description": "Three-letter country code (ISO 3166-1 alpha-3)." } } }, "PickupPointsResponse": { "type": "object", "description": "Response containing available pickup points for the specified location.", "properties": { "pickupPointDistances": { "type": "array", "description": "Array of pickup points available near the location.", "items": { "type": "object", "description": "Pickup point information.", "properties": { "pickupId": { "type": "string", "description": "Unique identifier of the pickup point." }, "pickupName": { "type": "string", "description": "Human-readable name of the pickup point." }, "distance": { "type": "number", "description": "Distance from the searched location in kilometers." }, "isActive": { "type": "boolean", "description": "Indicates if the pickup point is active." }, "address": { "type": "object", "description": "Physical address of the pickup point.", "properties": { "street": { "type": "string", "description": "Street name." }, "number": { "type": "string", "description": "Street number." }, "postalCode": { "type": "string", "description": "Postal code." }, "city": { "type": "string", "description": "City name." }, "state": { "type": "string", "description": "State or province code." }, "neighborhood": { "type": "string", "description": "Neighborhood name." } } }, "businessHours": { "type": "array", "description": "Business hours of the pickup point from Monday to Friday.", "items": { "type": "object", "description": "Business hours of the pickup point in a specific day of the week.", "properties": { "dayOfWeek": { "type": "integer", "description": "Day of the week identification, as in `0` = Sunday, `1` = Monday, `2` = Tuesday, `3` = Wednesday, `4` = Thursday, `5` = Friday, and `6` = Saturday.", "enum": [ 0, 1, 2, 3, 4, 5, 6 ] }, "openingTime": { "type": "string", "description": "Opening time of the pickup point in `HH:MM:SS` format." }, "closingTime": { "type": "string", "description": "Closing time of the pickup point in `HH:MM:SS` format." } } } } } } }, "pickupPointsHash": { "type": "string", "description": "Hash representing the pickup points context. This hash can be sent in the optional `pickupsHash` field of the [Get delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#get-/api/delivery-promise-suggestions) and the [Search delivery suggestions](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/delivery-promise-suggestions/_search) endpoints." } } }, "DeliverySuggestionRequest": { "type": "object", "description": "Request body for delivery suggestion queries.", "required": [ "products", "deliveryZonesHash" ], "properties": { "products": { "type": "array", "description": "Array of products to get delivery suggestions for. Must contain between 1 and 20 products.", "minItems": 1, "maxItems": 20, "items": { "type": "object", "description": "Product information for suggestion request.", "required": [ "productId" ], "properties": { "productId": { "type": "string", "description": "The unique identifier of the product.", "nullable": false }, "itemId": { "type": "string", "description": "The specific SKU ID. If omitted, all SKUs for the product are evaluated." } } } }, "deliveryZonesHash": { "type": "string", "description": "Hash representing the user's delivery context, which is a part of the fulfillment context. This hash is generated by the [Get delivery zones and pickup points hashes](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/zones/_search) endpoint and expires 30 minutes after being generated. This field is required in every request, including requests that send `pickupsHash`." }, "pickupsHash": { "type": "string", "description": "Hash representing the user's pickup context, which is a part of the fulfillment context. This hash corresponds to the `pickupPointsHash` field returned by the [Get delivery zones and pickup points hashes](https://developers.vtex.com/docs/api-reference/delivery-promise-suggestions-api#post-/api/logistics-shipping/zones/_search) endpoint and expires 30 minutes after being generated. This field is optional. If you send it, send it together with the required `deliveryZonesHash`." } } }, "DeliverySuggestionResponse": { "type": "object", "description": "Response containing delivery suggestions for requested products.", "properties": { "suggestions": { "type": "array", "description": "Array of delivery suggestions, with one entry corresponding to each product in the request.", "minItems": 1, "maxItems": 20, "items": { "type": "object", "description": "Delivery suggestion for a single product.", "required": [ "productId", "suggestions" ], "properties": { "productId": { "type": "string", "description": "The unique identifier of the product.", "nullable": false }, "suggestions": { "type": "object", "description": "Object containing delivery and pickup options suggestions.", "required": [ "delivery", "pickup" ], "properties": { "delivery": { "type": "array", "description": "Array of delivery option suggestions. An empty array indicates no delivery options are available for the current context.", "items": { "type": "object", "description": "Delivery option suggestion.", "properties": { "id": { "type": "string", "description": "The unique identifier for the specific delivery option (SLA)." }, "name": { "type": "string", "description": "A human-readable name for the delivery option (e.g., \"Express Delivery\")." }, "slaTimeTarget": { "type": "object", "description": "Object defining the time window for fulfillment.", "properties": { "from": { "type": "number", "description": "Minimum time for fulfillment." }, "to": { "type": "number", "description": "Maximum time for fulfillment." }, "unit": { "type": "string", "description": "Time unit: `h` for hours or `d` for days.", "enum": [ "h", "d" ] } } }, "conditions": { "type": "array", "description": "Tags indicating why the option was selected (e.g., `fastest`, `nearest`).", "items": { "type": "string", "description": "Condition tag (e.g., `fastest`, `nearest`)." } } } } }, "pickup": { "type": "array", "description": "Array of pickup option suggestions. An empty array indicates no pickup options are available for the current context.", "items": { "type": "object", "description": "Pickup option suggestion.", "properties": { "id": { "type": "string", "description": "The unique identifier for the specific pickup option (Store)." }, "name": { "type": "string", "description": "A human-readable name for the pickup option (e.g., \"Downtown Store\")." }, "slaTimeTarget": { "type": "object", "description": "Object defining the time window for fulfillment.", "properties": { "from": { "type": "number", "description": "Minimum time for fulfillment." }, "to": { "type": "number", "description": "Maximum time for fulfillment." }, "unit": { "type": "string", "description": "Time unit: `h` for hours or `d` for days.", "enum": [ "h", "d" ] } } }, "conditions": { "type": "array", "description": "Tags indicating why the option was selected (e.g., `fastest`, `nearest`).", "items": { "type": "string", "description": "Condition tag (e.g., `fastest`, `nearest`)." } } } } } } } } } } } }, "ErrorResponse": { "type": "object", "description": "Error response structure.", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Descriptive message of the error." } } } }, "securitySchemes": { "appKey": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppKey", "description": "Unique identifier of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "appToken": { "type": "apiKey", "in": "header", "name": "X-VTEX-API-AppToken", "description": "Secret token of the [API key](https://developers.vtex.com/docs/guides/api-authentication-using-api-keys)." }, "VtexIdclientAutCookie": { "type": "apiKey", "in": "header", "name": "VtexIdclientAutCookie", "description": "[User token](https://developers.vtex.com/docs/guides/api-authentication-using-user-tokens), valid for 24 hours." } } }, "tags": [ { "name": "Logistics shipping" }, { "name": "Delivery suggestions" } ] }