Gathering delivery promise information

Logistics

Learn how to retrieve the delivery zones, pickup points, and delivery suggestions needed to display delivery promise information in your storefront.

This feature is in beta, and we are actively working to improve it. If you have any questions, please contact our Support.

Delivery Promise is VTEX's solution that lets shoppers see only the products they can actually buy, taking into account product availability and the shipping methods valid for their delivery address. The Delivery Promise Suggestions API builds on this by surfacing the most relevant delivery and pickup options directly in the storefront, such as the fastest delivery available or the nearest pickup point.

This guide walks you through the data you need to collect before rendering any UI: the available delivery zones, the available pickup points, and the resulting delivery promise suggestions for a shopper's location.

Delivery zones

Use the POST Search delivery zones endpoint to retrieve the following information:

Delivery zone IDs
Delivery zones hash
Country code

Response example:


_10{
_10   "deliveryZoneIds": [
_10         "BRA_COUNTRY",
_10         "BRA_REGION_NORDESTE",
_10         "BRA_SUBSTATE_PB_INTERIOR"
_10   ],
_10   "deliveryZonesHash": "c3e1a42f7b9d4e81aafe24ba6e7b120f",
_10   "countryCode": "BRA"
_10}

Use the deliveryZonesHash value when you search for delivery suggestions.

Delivery pickup points

To retrieve the available pickup points for the shopper, use the POST Search pickup points endpoint.

Response example:


_56{
_56   "pickupPointDistances": [
_56         {
_56            "pickupId": "fulfillmentqa_vtexsp",
_56            "distance": 4.990988731384277,
_56            "pickupName": "VTEX SP",
_56            "isActive": true,
_56            "address": {
_56               "city": "São Paulo",
_56               "neighborhood": "Itaim Bibi",
_56               "number": "4440",
_56               "postalCode": "04538-132",
_56               "street": "Avenida Brigadeiro Faria Lima",
_56               "state": "SP"
_56            },
_56            "businessHours": [
_56               {
_56                     "dayOfWeek": 0,
_56                     "openingTime": "00:00:00",
_56                     "closingTime": "23:59:00"
_56               },
_56               {
_56                     "dayOfWeek": 1,
_56                     "openingTime": "00:00:00",
_56                     "closingTime": "23:59:00"
_56               },
_56               {
_56                     "dayOfWeek": 2,
_56                     "openingTime": "00:00:00",
_56                     "closingTime": "23:59:00"
_56               },
_56               {
_56                     "dayOfWeek": 3,
_56                     "openingTime": "00:00:00",
_56                     "closingTime": "23:59:00"
_56               },
_56               {
_56                     "dayOfWeek": 4,
_56                     "openingTime": "00:00:00",
_56                     "closingTime": "23:59:00"
_56               },
_56               {
_56                     "dayOfWeek": 5,
_56                     "openingTime": "00:00:00",
_56                     "closingTime": "23:59:00"
_56               },
_56               {
_56                     "dayOfWeek": 6,
_56                     "openingTime": "00:00:00",
_56                     "closingTime": "23:59:00"
_56               }
_56            ]
_56         }
_56      ],
_56   "pickupPointsHash": "b92e64d0a08f4c6785e6d0319cbad19a"
_56}

Use the pickupPointsHash value when you search for delivery suggestions.

Delivery suggestions

Use the POST Search delivery suggestions endpoint with the deliveryZonesHash and pickupPointsHash values in the request body to gather the delivery promise suggestions that will be presented in your storefront. You can use this endpoint for batch processing and for scenarios that involve multiple products.

The following example response illustrates the data you can expect:


_47{
_47      "suggestions": [
_47            {
_47                  "productId": "123",
_47                  "suggestions": {
_47                  "delivery": [
_47                        {
_47                              "id": "express-delivery",
_47                              "name": "Express Delivery",
_47                              "slaTimeTarget": {
_47                              "from": 0,
_47                              "to": 4,
_47                              "unit": "h"
_47                              },
_47                              "conditions": [
_47                              "fastest"
_47                              ]
_47                        },
_47                        {
_47                              "id": "standard-delivery",
_47                              "name": "Standard Delivery",
_47                              "slaTimeTarget": {
_47                              "from": 1,
_47                              "to": 3,
_47                              "unit": "d"
_47                              },
_47                              "conditions": []
_47                        }
_47                  ],
_47                  "pickup": [
_47                        {
_47                              "id": "store-downtown",
_47                              "name": "Downtown Store",
_47                              "slaTimeTarget": {
_47                              "from": 0,
_47                              "to": 2,
_47                              "unit": "h"
_47                              },
_47                              "conditions": [
_47                              "nearest"
_47                              ]
_47                        }
_47                  ]
_47                  }
_47            }
_47      ]
_47}