Delivery Promise Notification API
Delivery Promise is VTEX's solution that allows customers to view only the products they can buy in their shopping experience, considering both the product availability in the seller inventory and the valid shipping methods for their delivery address.
The Delivery Promise Notification API notifies the VTEX store of the external seller's product availability and delivery promises — that is, in which delivery zones, times, and methods the product is available.
When to use this API
This API is intended only for external sellers. It is not required for:
- Franchise accounts.
- Sellers using VTEX Seller Portal.
- VTEX sellers already integrated into the marketplace ecosystem.
In these cases, availability and delivery options are managed natively by VTEX.
Integration flow
Before notifying availability for an external seller's SKU, the SKU must exist in the marketplace's catalog. The full flow is:
- The external seller sends a SKU suggestion to the marketplace using the Send SKU suggestion endpoint.
- The marketplace approves the SKU suggestion.
- After the suggestion is approved, the product and SKU are created in the marketplace's VTEX Catalog.
- The external seller notifies the SKU availability and delivery promises using the Update external product availability endpoint.
- Delivery Promise indexes the product and SKU.
Performance benefits
When the marketplace uses Delivery Promise as the availability provider for both Search and Checkout, VTEX doesn't need to call your fulfillment simulation endpoint without a postal code to index products or display them in the storefront. Your endpoint only receives simulation requests that include a postal code, such as those from the cart and checkout.
PUT vs PATCH
- Use
PUTUpdate external product availability when you want to create or fully replace all promises for one or more items. - Use
PATCHUpdate delivery promises for an external seller's item when you want to update specific promises for a single item.
Before running a
PATCHfor an item, that item must have been previously created with aPUTrequest.PATCHis an update operation whose key is theidpreviously sent in thePUTrequest.
Making a SKU unavailable
To make a SKU unavailable for a given delivery context, send a request with availability: 0. This action explicitly updates the Delivery Promise state. Unlike Seller Portal integrations, this change is not automatically propagated and must be triggered via API.
Endpoints
Delivery promise
| Summary | Method | Path |
|---|---|---|
| Update external product availability | PUT | /api/delivery-promises/external-sellers/{sellerId}/products |
| Update delivery promises for an external seller's item | PATCH | /api/delivery-promises/external-sellers/{sellerId}/items/{itemId} |