{ "openapi": "3.0.0", "info": { "title": "Delivery Promise Notification API", "version": "1.0.0", "description": "[Delivery Promise](https://help.vtex.com/en/docs/tutorials/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.\r\n\r\nThe Delivery Promise Notification API notifies the VTEX store of the [external seller's](https://help.vtex.com/en/tutorial/integration-guide-for-marketplaces-seller-non-vtex--yMji0ow0rQuYgQsg26Kus) product availability and delivery promises — that is, in which delivery zones, times, and methods the product is available.\r\n\r\n## When to use this API\r\n\r\nThis API is intended only for [**external sellers**](https://help.vtex.com/en/tutorial/integration-guide-for-marketplaces-seller-non-vtex--yMji0ow0rQuYgQsg26Kus). It is not required for:\r\n\r\n- [Franchise accounts](https://help.vtex.com/en/docs/tutorials/what-is-a-franchise-account).\r\n- Sellers using [VTEX Seller Portal](https://help.vtex.com/en/docs/tutorials/how-to-set-up-your-store-on-seller-portal).\r\n- [VTEX sellers](https://help.vtex.com/en/tutorial/integrating-with-marketplace) already integrated into the [marketplace ecosystem](https://help.vtex.com/en/tutorial/integrating-with-marketplace).\r\n\r\nIn these cases, availability and delivery options are managed natively by VTEX.\r\n\r\n## Integration flow\r\n\r\nBefore notifying availability for an external seller's SKU, the SKU must exist in the marketplace's catalog. The full flow is:\r\n\r\n1. The external seller sends a SKU suggestion to the marketplace using the [Send SKU suggestion](https://developers.vtex.com/docs/api-reference/marketplace-apis-suggestions#put-/suggestions/-sellerId-/-sellerSkuId-) endpoint.\r\n2. The marketplace approves the SKU suggestion.\r\n3. After the suggestion is approved, the product and SKU are created in the marketplace's VTEX Catalog.\r\n4. The external seller notifies the SKU availability and delivery promises using the [Update external product availability](https://developers.vtex.com/docs/api-reference/delivery-promise-notification-api#put-/api/delivery-promises/external-sellers/-sellerId-/products) endpoint.\r\n5. Delivery Promise indexes the product and SKU.\r\n\r\n## Performance benefits\r\n\r\nWhen the marketplace uses Delivery Promise as the availability provider for both Search and Checkout, VTEX doesn't need to call your [fulfillment simulation endpoint](https://developers.vtex.com/docs/api-reference/marketplace-protocol-external-seller-fulfillment#post-/pvt/orderForms/simulation) 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.\r\n\r\n## `PUT` vs `PATCH`\r\n\r\n- Use `PUT` [Update external product availability](https://developers.vtex.com/docs/api-reference/delivery-promise-notification-api#put-/api/delivery-promises/external-sellers/-sellerId-/products) when you want to **create or fully replace** all promises for one or more items.\r\n- Use `PATCH` [Update delivery promises for an external seller's item](https://developers.vtex.com/docs/api-reference/delivery-promise-notification-api#patch-/api/delivery-promises/external-sellers/-sellerId-/items/-itemId-) when you want to **update specific promises** for a single item.\r\n\r\n>ℹ️ Before running a `PATCH` for an item, that item must have been previously created with a `PUT` request. `PATCH` is an update operation whose key is the `id` previously sent in the `PUT` request.\r\n\r\n## Making a SKU unavailable\r\n\r\nTo make a SKU unavailable for a given delivery context, send a request with `availability: 0`. This action explicitly updates the [Delivery Promise](https://help.vtex.com/en/docs/tutorials/delivery-promise) state. Unlike [Seller Portal](https://help.vtex.com/en/docs/tutorials/how-to-set-up-your-store-on-seller-portal) integrations, this change is not automatically propagated and must be triggered via API." }, "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/delivery-promises/external-sellers/{sellerId}/products": { "put": { "summary": "Update external product availability", "description": "Creates or fully updates delivery promises for one or more [external seller's](https://help.vtex.com/en/tutorial/integration-guide-for-marketplaces-seller-non-vtex--yMji0ow0rQuYgQsg26Kus) items, notifying VTEX of changes in product availability and delivery promises.\r\n\r\nThe 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.\r\n\r\n>ℹ️ This API is intended only for [**external sellers**](https://help.vtex.com/en/tutorial/integration-guide-for-marketplaces-seller-non-vtex--yMji0ow0rQuYgQsg26Kus). It is not required for [franchise accounts](https://help.vtex.com/en/docs/tutorials/what-is-a-franchise-account), sellers using [VTEX Seller Portal](https://help.vtex.com/en/docs/tutorials/how-to-set-up-your-store-on-seller-portal), or [VTEX sellers](https://help.vtex.com/en/tutorial/integrating-with-marketplace) already integrated into the [marketplace ecosystem](https://help.vtex.com/en/tutorial/integrating-with-marketplace). In these cases, availability and delivery options are managed natively by VTEX.\r\n\r\nUse this endpoint to **create or fully replace** the delivery promises for one or more external sellers' items. Each request sends the complete set of promises for the items included in the payload.\r\n\r\n>ℹ️ We recommend sending up to 1,000 items per request. To update more items, split them into multiple requests.\r\n\r\n## Making a SKU unavailable\r\n\r\nTo make a SKU unavailable for a given delivery context, send a `PUT` request with `availability: 0`. This action explicitly updates the [Delivery Promise](https://help.vtex.com/en/docs/tutorials/delivery-promise) state. Unlike [Seller Portal](https://help.vtex.com/en/docs/tutorials/how-to-set-up-your-store-on-seller-portal) integrations, this change is not automatically propagated and must be triggered via API.\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| Delivery Promises | ProductAvailability | **Notify Product Availability Change** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "tags": ["Delivery promise"], "parameters": [ { "name": "sellerId", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The seller's ID registered in the marketplace." }, { "name": "an", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The account name receiving the notification." }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "array", "description": "List of items to be updated. We recommend sending up to 1,000 items per request.", "items": { "type": "object", "description": "Item availability and delivery promises.", "required": [ "itemId", "availability", "promises" ], "properties": { "itemId": { "type": "string", "description": "SKU ID in the external seller's own system. This is not the marketplace's product ID or SKU ID in VTEX. VTEX internally maps this value to the corresponding product and SKU already registered in the marketplace account." }, "productId": { "type": "string", "description": "Product unique identifier." }, "availability": { "type": "integer", "description": "Total available items for the SKU across all promises. Send `0` to make the SKU unavailable in this delivery context." }, "promises": { "type": "array", "description": "List of delivery promises.", "items": { "type": "object", "description": "Delivery promise details.", "required": [ "availability", "deliveryChannel", "deliveryZoneIds" ], "properties": { "availability": { "type": "integer", "description": "Available items for this delivery promise. Send `0` to make this specific promise unavailable." }, "deliveryChannel": { "type": "string", "enum": [ "delivery" ], "description": "Delivery channel type. The only accepted value is `delivery`." }, "deliveryZoneIds": { "type": "array", "minItems": 1, "description": "List of delivery zones where the item is available. Any country is supported. To set a delivery zone for an entire country, use the convention `{countryCode}_COUNTRY`, where `{countryCode}` is the three-letter [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code. For example, `BRA_COUNTRY` for Brazil or `ARG_COUNTRY` for Argentina.", "items": { "type": "string", "description": "Delivery zone unique identifier.", "enum": [ "BRA_COUNTRY", "BRA_REGION_NORTE", "BRA_REGION_CENTRO_OESTE", "BRA_REGION_NORDESTE", "BRA_REGION_SUDESTE", "BRA_REGION_SUL", "BRA_SUBSTATE_DF_CAPITAL", "BRA_SUBSTATE_DF_INTERIOR", "BRA_SUBSTATE_GO_CAPITAL", "BRA_SUBSTATE_GO_INTERIOR", "BRA_SUBSTATE_MT_CAPITAL", "BRA_SUBSTATE_MT_INTERIOR", "BRA_SUBSTATE_MS_CAPITAL", "BRA_SUBSTATE_MS_INTERIOR", "BRA_SUBSTATE_BA_CAPITAL", "BRA_SUBSTATE_BA_REG_METROPOLITANA", "BRA_SUBSTATE_BA_INTERIOR", "BRA_SUBSTATE_SE_CAPITAL", "BRA_SUBSTATE_SE_INTERIOR", "BRA_SUBSTATE_PE_CAPITAL", "BRA_SUBSTATE_PE_REG_METROPOLITANA", "BRA_SUBSTATE_PE_INTERIOR", "BRA_SUBSTATE_AL_CAPITAL", "BRA_SUBSTATE_AL_INTERIOR", "BRA_SUBSTATE_PB_CAPITAL", "BRA_SUBSTATE_PB_INTERIOR", "BRA_SUBSTATE_RN_CAPITAL", "BRA_SUBSTATE_RN_INTERIOR", "BRA_SUBSTATE_CE_CAPITAL", "BRA_SUBSTATE_CE_REG_METROPOLITANA", "BRA_SUBSTATE_CE_INTERIOR", "BRA_SUBSTATE_PI_CAPITAL", "BRA_SUBSTATE_PI_INTERIOR", "BRA_SUBSTATE_MA_CAPITAL", "BRA_SUBSTATE_MA_INTERIOR", "BRA_SUBSTATE_PA_CAPITAL", "BRA_SUBSTATE_PA_REG_METROPOLITANA", "BRA_SUBSTATE_PA_INTERIOR", "BRA_SUBSTATE_AP_CAPITAL", "BRA_SUBSTATE_AP_INTERIOR", "BRA_SUBSTATE_AM_CAPITAL", "BRA_SUBSTATE_AM_INTERIOR", "BRA_SUBSTATE_RR_CAPITAL", "BRA_SUBSTATE_RR_INTERIOR", "BRA_SUBSTATE_AC_CAPITAL", "BRA_SUBSTATE_AC_INTERIOR", "BRA_SUBSTATE_TO_CAPITAL", "BRA_SUBSTATE_TO_INTERIOR", "BRA_SUBSTATE_RO_CAPITAL", "BRA_SUBSTATE_RO_INTERIOR", "BRA_SUBSTATE_SP_CAPITAL", "BRA_SUBSTATE_SP_REG_METROPOLITANA", "BRA_SUBSTATE_SP_LITORAL", "BRA_SUBSTATE_SP_INTERIOR", "BRA_SUBSTATE_RJ_CAPITAL", "BRA_SUBSTATE_RJ_REG_METROPOLITANA", "BRA_SUBSTATE_RJ_INTERIOR", "BRA_SUBSTATE_ES_CAPITAL", "BRA_SUBSTATE_ES_INTERIOR", "BRA_SUBSTATE_MG_CAPITAL", "BRA_SUBSTATE_MG_REG_METROPOLITANA", "BRA_SUBSTATE_MG_INTERIOR", "BRA_SUBSTATE_PR_CAPITAL", "BRA_SUBSTATE_PR_REG_METROPOLITANA", "BRA_SUBSTATE_PR_INTERIOR", "BRA_SUBSTATE_SC_CAPITAL", "BRA_SUBSTATE_SC_REG_METROPOLITANA", "BRA_SUBSTATE_SC_INTERIOR", "BRA_SUBSTATE_RS_CAPITAL", "BRA_SUBSTATE_RS_REG_METROPOLITANA", "BRA_SUBSTATE_RS_INTERIOR", "USA_COUNTRY", "USA_DIVISION_NEW_ENGLAND", "USA_STATE_CT", "USA_STATE_ME", "USA_STATE_MA", "USA_STATE_NH", "USA_STATE_RI", "USA_STATE_VT", "USA_DIVISION_MIDDLE_ATLANTIC", "USA_STATE_NJ", "USA_STATE_NY", "USA_STATE_PA", "USA_DIVISION_EAST_NORTH_CENTRAL", "USA_STATE_IL", "USA_STATE_IN", "USA_STATE_MI", "USA_STATE_OH", "USA_STATE_WI", "USA_DIVISION_WEST_NORTH_CENTRAL", "USA_STATE_IA", "USA_STATE_KS", "USA_STATE_MN", "USA_STATE_MO", "USA_STATE_NE", "USA_STATE_ND", "USA_STATE_SD", "USA_DIVISION_SOUTH_ATLANTIC", "USA_STATE_DE", "USA_STATE_FL", "USA_STATE_GA", "USA_STATE_MD", "USA_STATE_NC", "USA_STATE_SC", "USA_STATE_VA", "USA_STATE_WV", "USA_STATE_DC", "USA_DIVISION_EAST_SOUTH_CENTRAL", "USA_STATE_AL", "USA_STATE_KY", "USA_STATE_MS", "USA_STATE_TN", "USA_DIVISION_WEST_SOUTH_CENTRAL", "USA_STATE_AR", "USA_STATE_LA", "USA_STATE_OK", "USA_STATE_TX", "USA_DIVISION_MOUNTAIN", "USA_STATE_AZ", "USA_STATE_CO", "USA_STATE_ID", "USA_STATE_MT", "USA_STATE_NV", "USA_STATE_NM", "USA_STATE_UT", "USA_STATE_WY", "USA_DIVISION_PACIFIC", "USA_STATE_AK", "USA_STATE_CA", "USA_STATE_HI", "USA_STATE_OR", "USA_STATE_WA" ] } }, "deliveryInfo": { "type": "object", "description": "Delivery method details. The `id` value sent here is the key used to update this promise later via [Update delivery promises for an external seller's item](https://developers.vtex.com/docs/api-reference/delivery-promise-notification-api#patch-/api/delivery-promises/external-sellers/-sellerId-/items/-itemId-) endpoint.", "properties": { "id": { "type": "string", "description": "Unique identifier of the delivery method. This value is the key used to update this promise later via [Update delivery promises for an external seller's item](https://developers.vtex.com/docs/api-reference/delivery-promise-notification-api#patch-/api/delivery-promises/external-sellers/-sellerId-/items/-itemId-) endpoint." }, "name": { "type": "string", "description": "Display name of the delivery method." }, "deliveryTime": { "type": "string", "description": "Estimated delivery time in `dd.hh:mm:ss` format. For example, `2.02:00:00` represents an estimated delivery time of two days and two hours. Days are counted as calendar days, so weekends and holidays are not treated differently." } } } } } } } } }, "example": [ { "itemId": "1234", "productId": "XPTO", "availability": 7, "promises": [ { "availability": 5, "deliveryChannel": "delivery", "deliveryZoneIds": ["BRA_COUNTRY"], "deliveryInfo": { "id": "Prime5Days", "name": "Same Week", "deliveryTime": "5.00:00:00" } }, { "availability": 3, "deliveryChannel": "delivery", "deliveryZoneIds": ["BRA_COUNTRY"], "deliveryInfo": { "id": "Prime2Day", "name": "Same Day", "deliveryTime": "1.00:00:00" } } ] } ] } } }, "responses": { "202": { "description": "Accept" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message. Invalid API key or token." } } }, "example": { "error": "Invalid API key or token." } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message. Inadequate permissions." } } }, "example": { "error": "Inadequate permissions." } } } }, "429": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message. Request limit exceeded." } } }, "example": { "error": "Request limit exceeded." } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message. Unexpected application failure." } } }, "example": { "error": "Unexpected application failure." } } } } }, "security": [ { "appKey": [], "appToken": [] } ] } }, "/api/delivery-promises/external-sellers/{sellerId}/items/{itemId}": { "patch": { "summary": "Update delivery promises for an external seller's item", "description": "Updates one or more delivery promises of a single [external seller's](https://help.vtex.com/en/tutorial/integration-guide-for-marketplaces-seller-non-vtex--yMji0ow0rQuYgQsg26Kus) item, identified by the path parameter `itemId`.\r\n\r\nThe 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.\r\n\r\n>ℹ️ This API is intended only for [**external sellers**](https://help.vtex.com/en/tutorial/integration-guide-for-marketplaces-seller-non-vtex--yMji0ow0rQuYgQsg26Kus). It is not required for [franchise accounts](https://help.vtex.com/en/docs/tutorials/what-is-a-franchise-account), sellers using [VTEX Seller Portal](https://help.vtex.com/en/docs/tutorials/how-to-set-up-your-store-on-seller-portal), or [VTEX sellers](https://help.vtex.com/en/tutorial/integrating-with-marketplace) already integrated into the [marketplace ecosystem](https://help.vtex.com/en/tutorial/integrating-with-marketplace). In these cases, availability and delivery options are managed natively by VTEX.\r\n\r\nUse this endpoint to update one or more delivery promises of a single external seller's item. A `PATCH` request always targets a single `itemId`, but you can update as many promises as needed within that item.\r\n\r\nEach promise to be updated must be identified by `id` (the same value previously sent as `deliveryInfo.id` in a `PUT` request). This field is required because, without it, the API cannot determine which promise of that item should be updated.\r\n\r\n>ℹ️ Before running a `PATCH` for an item, that item must have been previously created with a `PUT` request. `PATCH` is an update operation whose key is the `id` previously sent in the Update external product availability request.\r\n\r\n## Making a SKU unavailable\r\n\r\nTo make a SKU unavailable for a given delivery context, send a `PATCH` request with `availability: 0`. This action explicitly updates the [Delivery Promise](https://help.vtex.com/en/docs/tutorials/delivery-promise) state. Unlike [Seller Portal](https://help.vtex.com/en/docs/tutorials/how-to-set-up-your-store-on-seller-portal) integrations, this change is not automatically propagated and must be triggered via API.\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| Delivery Promises | ProductAvailability | **Notify Product Availability Change** |\r\n\r\nThere are no applicable [predefined roles](https://help.vtex.com/en/tutorial/predefined-roles--jGDurZKJHvHJS13LnO7Dy) for this resource list. You must [create a custom role](https://help.vtex.com/en/tutorial/roles--7HKK5Uau2H6wxE1rH5oRbc#creating-a-role) and add at least one of the resources above in order to use this endpoint. To learn more about machine authentication at VTEX, see [Authentication overview](https://developers.vtex.com/docs/guides/authentication).\r\n\r\n>\u2757 To prevent integrations from having excessive permissions, consider the [best practices for managing API keys](https://help.vtex.com/en/tutorial/best-practices-api-keys--7b6nD1VMHa49aI5brlOvJm) when assigning License Manager roles to integrations.", "tags": ["Delivery promise"], "parameters": [ { "name": "sellerId", "in": "path", "required": true, "description": "External seller identifier.", "schema": { "type": "string", "example": "TALD41516202766265" } }, { "name": "itemId", "in": "path", "required": true, "description": "SKU ID in the external seller's own system, the same value sent as `itemId` in the [Update external product availability](https://developers.vtex.com/docs/api-reference/delivery-promise-notification-api#put-/api/delivery-promises/external-sellers/-sellerId-/products) request. This is not the marketplace's product ID or SKU ID in VTEX.", "schema": { "type": "string", "example": "11167-10968-34" } }, { "$ref": "#/components/parameters/Content-Type" }, { "$ref": "#/components/parameters/Accept" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "Delivery promises update payload.", "properties": { "availability": { "type": "integer", "description": "Total available items for the SKU across all promises. Send `0` to make the SKU unavailable in this delivery context." }, "promises": { "type": "array", "description": "List of delivery promises.", "items": { "type": "object", "description": "Delivery promise details.", "properties": { "availability": { "type": "integer", "description": "Available items for this delivery promise. Send `0` to make this specific promise unavailable." }, "deliveryChannel": { "type": "string", "enum": [ "delivery" ], "description": "Delivery channel type. The only accepted value is `delivery`." }, "deliveryZoneIds": { "type": "array", "minItems": 1, "description": "List of delivery zones where the item is available. Any country is supported. To set a delivery zone for an entire country, use the convention `{countryCode}_COUNTRY`, where `{countryCode}` is the three-letter [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code. For example, `BRA_COUNTRY` for Brazil or `ARG_COUNTRY` for Argentina.", "items": { "type": "string", "description": "Delivery zone unique identifier.", "enum": [ "BRA_COUNTRY", "BRA_REGION_NORTE", "BRA_REGION_CENTRO_OESTE", "BRA_REGION_NORDESTE", "BRA_REGION_SUDESTE", "BRA_REGION_SUL", "BRA_SUBSTATE_DF_CAPITAL", "BRA_SUBSTATE_DF_INTERIOR", "BRA_SUBSTATE_GO_CAPITAL", "BRA_SUBSTATE_GO_INTERIOR", "BRA_SUBSTATE_MT_CAPITAL", "BRA_SUBSTATE_MT_INTERIOR", "BRA_SUBSTATE_MS_CAPITAL", "BRA_SUBSTATE_MS_INTERIOR", "BRA_SUBSTATE_BA_CAPITAL", "BRA_SUBSTATE_BA_REG_METROPOLITANA", "BRA_SUBSTATE_BA_INTERIOR", "BRA_SUBSTATE_SE_CAPITAL", "BRA_SUBSTATE_SE_INTERIOR", "BRA_SUBSTATE_PE_CAPITAL", "BRA_SUBSTATE_PE_REG_METROPOLITANA", "BRA_SUBSTATE_PE_INTERIOR", "BRA_SUBSTATE_AL_CAPITAL", "BRA_SUBSTATE_AL_INTERIOR", "BRA_SUBSTATE_PB_CAPITAL", "BRA_SUBSTATE_PB_INTERIOR", "BRA_SUBSTATE_RN_CAPITAL", "BRA_SUBSTATE_RN_INTERIOR", "BRA_SUBSTATE_CE_CAPITAL", "BRA_SUBSTATE_CE_REG_METROPOLITANA", "BRA_SUBSTATE_CE_INTERIOR", "BRA_SUBSTATE_PI_CAPITAL", "BRA_SUBSTATE_PI_INTERIOR", "BRA_SUBSTATE_MA_CAPITAL", "BRA_SUBSTATE_MA_INTERIOR", "BRA_SUBSTATE_PA_CAPITAL", "BRA_SUBSTATE_PA_REG_METROPOLITANA", "BRA_SUBSTATE_PA_INTERIOR", "BRA_SUBSTATE_AP_CAPITAL", "BRA_SUBSTATE_AP_INTERIOR", "BRA_SUBSTATE_AM_CAPITAL", "BRA_SUBSTATE_AM_INTERIOR", "BRA_SUBSTATE_RR_CAPITAL", "BRA_SUBSTATE_RR_INTERIOR", "BRA_SUBSTATE_AC_CAPITAL", "BRA_SUBSTATE_AC_INTERIOR", "BRA_SUBSTATE_TO_CAPITAL", "BRA_SUBSTATE_TO_INTERIOR", "BRA_SUBSTATE_RO_CAPITAL", "BRA_SUBSTATE_RO_INTERIOR", "BRA_SUBSTATE_SP_CAPITAL", "BRA_SUBSTATE_SP_REG_METROPOLITANA", "BRA_SUBSTATE_SP_LITORAL", "BRA_SUBSTATE_SP_INTERIOR", "BRA_SUBSTATE_RJ_CAPITAL", "BRA_SUBSTATE_RJ_REG_METROPOLITANA", "BRA_SUBSTATE_RJ_INTERIOR", "BRA_SUBSTATE_ES_CAPITAL", "BRA_SUBSTATE_ES_INTERIOR", "BRA_SUBSTATE_MG_CAPITAL", "BRA_SUBSTATE_MG_REG_METROPOLITANA", "BRA_SUBSTATE_MG_INTERIOR", "BRA_SUBSTATE_PR_CAPITAL", "BRA_SUBSTATE_PR_REG_METROPOLITANA", "BRA_SUBSTATE_PR_INTERIOR", "BRA_SUBSTATE_SC_CAPITAL", "BRA_SUBSTATE_SC_REG_METROPOLITANA", "BRA_SUBSTATE_SC_INTERIOR", "BRA_SUBSTATE_RS_CAPITAL", "BRA_SUBSTATE_RS_REG_METROPOLITANA", "BRA_SUBSTATE_RS_INTERIOR", "USA_COUNTRY", "USA_DIVISION_NEW_ENGLAND", "USA_STATE_CT", "USA_STATE_ME", "USA_STATE_MA", "USA_STATE_NH", "USA_STATE_RI", "USA_STATE_VT", "USA_DIVISION_MIDDLE_ATLANTIC", "USA_STATE_NJ", "USA_STATE_NY", "USA_STATE_PA", "USA_DIVISION_EAST_NORTH_CENTRAL", "USA_STATE_IL", "USA_STATE_IN", "USA_STATE_MI", "USA_STATE_OH", "USA_STATE_WI", "USA_DIVISION_WEST_NORTH_CENTRAL", "USA_STATE_IA", "USA_STATE_KS", "USA_STATE_MN", "USA_STATE_MO", "USA_STATE_NE", "USA_STATE_ND", "USA_STATE_SD", "USA_DIVISION_SOUTH_ATLANTIC", "USA_STATE_DE", "USA_STATE_FL", "USA_STATE_GA", "USA_STATE_MD", "USA_STATE_NC", "USA_STATE_SC", "USA_STATE_VA", "USA_STATE_WV", "USA_STATE_DC", "USA_DIVISION_EAST_SOUTH_CENTRAL", "USA_STATE_AL", "USA_STATE_KY", "USA_STATE_MS", "USA_STATE_TN", "USA_DIVISION_WEST_SOUTH_CENTRAL", "USA_STATE_AR", "USA_STATE_LA", "USA_STATE_OK", "USA_STATE_TX", "USA_DIVISION_MOUNTAIN", "USA_STATE_AZ", "USA_STATE_CO", "USA_STATE_ID", "USA_STATE_MT", "USA_STATE_NV", "USA_STATE_NM", "USA_STATE_UT", "USA_STATE_WY", "USA_DIVISION_PACIFIC", "USA_STATE_AK", "USA_STATE_CA", "USA_STATE_HI", "USA_STATE_OR", "USA_STATE_WA" ] } }, "id": { "type": "string", "description": "Unique identifier of the delivery method. Required to identify which promise of the item must be updated. This value must match the `deliveryInfo.id` previously sent in a [Update external product availability](https://developers.vtex.com/docs/api-reference/delivery-promise-notification-api#put-/api/delivery-promises/external-sellers/-sellerId-/products) request." }, "name": { "type": "string", "description": "Display name of the delivery method." }, "deliveryTime": { "type": "string", "description": "Estimated delivery time in `dd.hh:mm:ss` format. For example, `2.02:00:00` represents an estimated delivery time of two days and two hours. Days are counted as calendar days, so weekends and holidays are not treated differently." } }, "required": [ "availability", "deliveryZoneIds", "id" ] }, "minItems": 1 }, "timestamp": { "type": "string", "description": "Timestamp when this update was generated (ISO 8601).", "format": "date-time" } }, "required": [ "availability", "promises", "timestamp" ] }, "example": { "availability": 12, "promises": [ { "availability": 9, "deliveryChannel": "delivery", "deliveryZoneIds": ["BRA_COUNTRY"], "id": "Prime5Days", "name": "Same Week", "deliveryTime": "5.00:00:00" }, { "availability": 3, "deliveryChannel": "delivery", "deliveryZoneIds": ["BRA_COUNTRY"], "id": "Prime2Day", "name": "Same Day", "deliveryTime": "1.00:00:00" } ], "timestamp": "2025-08-07T14:52:20" } } } }, "responses": { "200": { "description": "OK" }, "400": { "description": "Bad Request\r\n\r\n Missing timestamp or invalid timestamp format.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message." } } }, "example": { "error": "The provided timestamp is invalid" } } } }, "500": { "description": "Internal Server Error\r\n\r\n Missing availability.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message." } } }, "example": { "error": "The provided availability is invalid" } } } } }, "security": [ { "appKey": [], "appToken": [] } ] } } }, "components": { "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." } }, "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" } } } }, "tags": [ { "name": "Delivery Promise", "description": "Operations related to the delivery promise." } ] }