Gathering delivery promise information
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 and pickup points hashes
Use the POST Get delivery zones and pickup points hashes endpoint to retrieve, in a single request, the delivery zones and pickup points available for a shopper's location, along with the hashes that represent them:
- Delivery zone IDs
- Delivery zones hash
- Pickup points near the location
- Pickup points hash
Response example:
_16{_16 "deliveryZoneIds": [_16 "BRA_COUNTRY",_16 "BRA_REGION_NORDESTE",_16 "BRA_SUBSTATE_PB_INTERIOR"_16 ],_16 "deliveryZonesHash": "c3e1a42f7b9d4e81aafe24ba6e7b120f",_16 "pickupPointsHash": "b92e64d0a08f4c6785e6d0319cbad19a",_16 "pickupDistances": [_16 {_16 "pickupId": "fulfillmentqa_vtexsp",_16 "distance": 4.990988731384277,_16 "pickupName": "VTEX SP"_16 }_16 ]_16}
Use the deliveryZonesHash and pickupPointsHash values when you search for delivery suggestions.
Both hashes 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.
If a hash expires before use, generate a new one by calling 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.
Delivery Promise 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
deliveryZonesHashandpickupPointsHashvalues expire 30 minutes after being generated. Requests sent with an expired hash may be rejected or return invalid responses. To get new hashes, call thePOSTGet delivery zones and pickup points hashes endpoint again.
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}