Delivery Promise Suggestions API headless integration
This guide explains how to integrate the Delivery Promise Suggestions API into any storefront to display delivery promises and pickup options, creating meaningful visual indicators for shoppers.
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 new solution that allows customers to view only the products they can buy in their shopping experience, considering both the product availability and valid shipping methods for their delivery address. To further enhance this experience, the Delivery Promise Suggestions API allows you to highlight the most relevant delivery options directly in the storefront.
In this guide, you will learn how to integrate the Delivery Promise Suggestions API to display delivery promises and pickup options to shoppers in your headless storefront.
An error occurred while loading the image https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/docs/guides/Logistics/delivery-promise-suggestions-api-integration_1.png
Before you implement the storefront components, you must gather the delivery information that will be shown to the shopper by identifying the delivery zones and pickup points available for their location. This fulfillment context is then represented by two hashes (the delivery zones hash and the pickup points hash), which serve as a compact, precomputed snapshot of all relevant logistics configurations. Rather than recalculating these options on every request, these hashes make it possible to retrieve accurate suggestions more quickly, with lower latency and greater consistency across the shopping experience.
For step-by-step instructions on how to retrieve the delivery zones, pickup points, and delivery suggestions through the API, see the Gathering delivery promise information guide.
Generating UI elements
Your storefront must translate the API response into user-facing visual indicators. This section explains how to map response fields into shopper-friendly messages.
Interpretation of slaTimeTarget
The slaTimeTarget defines a relative fulfillment window. Specifically, it indicates the latest calendar day (or hour) by which delivery or pickup must occur. The system already considers weekends, holidays, and logistics rules when calculating this deadline.
If you need to apply additional business rules outside the logistics configuration (for example, special events or campaign-specific promises), implement that logic in your storefront. Using the computed deadline, you can generate contextual messaging such as “Receive before Christmas” when applicable.
The target date is always calculated relative to when the API is called. For example, { "to": 2, "unit": "d" } means fulfillment must occur within the next two calendar days.
Mapping delivery tags
Use the following table to map delivery SLAs to suggested tags:
| Fulfillment condition | slaTimeTarget | Suggested badge |
|---|---|---|
| Same-day delivery | { "to": 0, "unit": "d" } | "Receive Today" |
| Next-day delivery | { "to": 1, "unit": "d" } | "Receive Tomorrow" |
| Standard delivery | { "to": X, "unit": "d" } (X > 1) | "Receive in X days" |
| Express delivery | { "to": X, "unit": "h" } | "Receive in X hours" |
Mapping pickup tags
Use the following table to map pickup SLAs to suggested badges:
| Fulfillment condition | slaTimeTarget | Suggested badge |
|---|---|---|
| Same-day pickup | { "to": 0 } | "Pickup Today" |
| Express pickup | { "unit": "h" } | "Pickup in X hours" |
| Nearest location | Distance data must be available in the response | "Store at Y km from you" |
| Store name | Store name must be available in the response | "Pickup at Downtown Store" |
Display suggestions by context
Use different display strategies depending on where the shopper sees this information:
| Context | Display recommendation |
|---|---|
| PLP (Product Listing Page) | Show the top delivery and pickup suggestions for each product. Trigger display after Intelligent Search results have loaded. |
| PDP (Product Detail Page) | Show all available delivery and pickup options. Trigger display when the page loads or whenever the shopper’s location is updated. |
If you do not refresh the fulfillment context when the shopper's location changes, the delivery and pickup suggestions may become outdated or inaccurate. To ensure recommendations are always correct, refresh the context on every location change, make a batch request for all visible product IDs, and request suggestions for the currently displayed product (including its variants, if relevant).
End-to-end workflow example
This example illustrates the flow from shopper input to UI display:
- Input: The shopper provides a ZIP code, or the storefront detects their location.
- Context update: Create or refresh the fulfillment context whenever the location changes. Keep the context active by refreshing it before it becomes stale.
- Products fetch: The storefront identifies the relevant product IDs (for example, from a search results page).
- API request: Storefront calls
POSTSearch delivery suggestions with product IDs and thedeliveryZonesHashandpickupsHash. - API response: The API returns recommendations, for example:
- Delivery:
slaTimeTarget: {to: 2, unit: "d"},name: "Express Delivery" - Pickup:
slaTimeTarget: {to: 2, unit: "h"},name: "Downtown Store"
- Delivery:
- Storefront render: The storefront renders UI components, for example:
- "Express Delivery (1–2 days)"
- "Pickup Today at Downtown Store"