This feature is in open beta phase. If you're interested in testing it, contact our Support team.

The Delivery Promise (Beta) feature helps create a more accurate and reliable shopping experience by ensuring customers only see products the store can deliver to the provided address or pick up at available locations.

Availability is determined by the following rules:

• When a pickup point is selected — whether in the header or on its own page — the system displays all available pickup points within a 50 km radius configured in Checkout. There's no limit to the number of pickup points displayed.
• For the nearby pickup filter, pickup points within a 10 km radius of the shopper's location are displayed, with a maximum of 40 pickup points.

Delivery Promise supports any seller architecture (franchise accounts, VTEX Sellers, Seller Portal, and external sellers).

If you're building your storefront with Store Framework, you can enable this experience using two key apps:

• Delivery Promise Components: Used to display blocks for postal code, delivery versus pickup, and pickup point selection.
• Search Result: Used to implement sidebar filters.

Additionally, you can leverage the Delivery Promise Suggestions API to display delivery-related tags and badges directly on product cards in the Product Listing Page (PLP), such as "Same Day Delivery", "Express Delivery", and "Pickup Today". Showing these suggestions brings delivery context into the shopping journey earlier, improving product discoverability and conversion rates. For more details, see Gathering delivery promise information.

This guide walks you through the basic setup needed to implement Delivery Promise in your store.

Explore the Delivery Promise Figma library to learn more about component specs, usage guidelines, reference use cases, and behavioral patterns.

To enable Delivery Promise in your store, you must meet the following conditions:

• The store must use Intelligent Search.
• Check whether you've got version 0.5.0 or later of the search-session app installed. To do this, run the vtex list command in your terminal and search for the app in the results. If you don't have this app installed, run the command vtex install vtex.search-session.
• Your storefront must be built with Store Framework to enable the components in this guide. If you use FastStore, check the FastStore Delivery Promise implementation guide. If your store is headless, see Delivery Promise for headless stores.

Contact our Support team to request the activation of Delivery Promise.

To use Delivery Promise, customers must provide a delivery address early in their shopping journey. The delivery-promise-components app exposes Store Framework blocks that collect the location and, optionally, the fulfillment method (delivery vs. pickup or a specific pickup point).

1. Add the delivery-promise-components app to your theme dependencies in manifest.json as shown below:

   
   

   _10

   "dependencies": {

   _10

   "vtex.delivery-promise-components": "1.x"

   _10

   }

   
   

2. Declare the blocks in your theme header (or another layout that should show the controls). The app exposes three header blocks.

   Block	Description
   shopper-location-setter	Required. Collects the shopper's location (postal code or equivalent). This value drives all Delivery Promise subsequent availability calculations and filters.
   shipping-method-selector	Optional. A control for choosing between delivery and pickup after setting a location.
   pickup-point-selector	Optional. A control for choosing which pickup point to use after setting a location.

   The shopper-location-setter block is required, and you must always include it in the header. shipping-method-selector and pickup-point-selector are optional. These blocks complement the location setter but don't replace it, since both depend on the location already set in the session. Add them only if you want to expose additional controls in the UI. Otherwise, keep the header simple: either shopper-location-setter alone, or shopper-location-setter paired with one of the selectors. Using all three together is possible but uncommon.

   Choose the configuration that matches your use case:

   Location only

   Use the shopper-location-setter block when you only need the shopper to provide their location, without separate header controls for shipping method or store.

   Example:

   
   

   _11

   "header-row#1-desktop": {

   _11

   "children": ["shopper-location-setter"]

   _11

   },

   _11

   _11

   "shopper-location-setter": {

   _11

   "props": {

   _11

   "required": false,

   _11

   "mode": "default",

   _11

   "showLocationDetectorButton": false

   _11

   }

   _11

   }

   
   

   Location + shipping method

   Use shopper-location-setter and shipping-method-selector when you want the header to make the delivery or pickup choice explicit right after the shopper enters a location.

   Example:

   
   

   _21

   "header-row#1-desktop": {

   _21

   "children": [

   _21

   "shopper-location-setter",

   _21

   "shipping-method-selector"

   _21

   ]

   _21

   },

   _21

   _21

   "shopper-location-setter": {

   _21

   "props": {

   _21

   "required": false,

   _21

   "mode": "default",

   _21

   "showLocationDetectorButton": false

   _21

   }

   _21

   },

   _21

   _21

   "shipping-method-selector": {

   _21

   "props": {

   _21

   "required": false,

   _21

   "mode": "default"

   _21

   }

   _21

   }

   
   

   Location + pickup point

   Use shopper-location-setter and pickup-point-selector when pickup is a central part of your experience, and you want both "where am I?" and "which store?" visible in the header.

   Example:

   
   

   _20

   "header-row#1-desktop": {

   _20

   "children": [

   _20

   "shopper-location-setter",

   _20

   "pickup-point-selector"

   _20

   ]

   _20

   },

   _20

   _20

   "shopper-location-setter": {

   _20

   "props": {

   _20

   "required": false,

   _20

   "mode": "default",

   _20

   "showLocationDetectorButton": false

   _20

   }

   _20

   },

   _20

   _20

   "pickup-point-selector": {

   _20

   "props": {

   _20

   "mode": "default"

   _20

   }

   _20

   }

   
   

3. Use the props below to customize each block's behavior.

   shopper-location-setter

   Prop	Type	Default	Description
   required	boolean	false	When true, opens a non-dismissible postal code modal until the shopper sets a valid code. When false, uses the popover flow.
   mode	string	"default"	Display mode: default or icon.
   showLocationDetectorButton	boolean	false	Shows the control that uses the browser geolocation API to suggest the postal code. Available only on this block.

   shipping-method-selector

   Prop	Type	Default	Description
   required	boolean	false	When true, the shipping method modal can't be dismissed until a method is selected (after entering a postal code).
   mode	string	"default"	Display mode: default or icon.

   pickup-point-selector

   Prop	Type	Default	Description
   mode	string	"default"	Display mode: default or icon.

To display Delivery Promise filters in the search sidebar, configure the Search Result app as described below.

Delivery Promise filters are a beta feature and may be subject to breaking changes. If you customize this functionality, ensure your implementation can handle future updates.

1. In your theme's manifest.json, add the search-result app as a dependency:

   
   

   _10

   "dependencies": {

   _10

   "vtex.search-result": "3.x"

   _10

   }

   
   

2. Make sure your theme uses either the search-result-layout.desktop or the search-result-layout.mobile block, depending on the layout. Inside these layouts, include the filter-navigator.v3 block so the sidebar can render filters:

   store/search.json

   
   

   _23

   {

   _23

   "store.search#default": {

   _23

   "blocks": ["search-result-layout"]

   _23

   },

   _23

   "search-result-layout": {

   _23

   "children": [

   _23

   "search-result-layout.desktop",

   _23

   "search-result-layout.mobile"

   _23

   ]

   _23

   },

   _23

   "search-result-layout.desktop": {

   _23

   "children": ["filter-navigator.v3", "search-content"],

   _23

   "props": {

   _23

   "showShippingMethodFacet": true

   _23

   }

   _23

   },

   _23

   "search-result-layout.mobile": {

   _23

   "children": ["filter-navigator.v3", "search-content"],

   _23

   "props": {

   _23

   "showShippingMethodFacet": true

   _23

   }

   _23

   }

   _23

   }

   
   

3. Set showShippingMethodFacet to true in each flexible search layout where you want the Delivery Promise filters to appear. By default, this property is disabled, so the shipping method filter remains hidden unless you explicitly enable it. The example above enables it on both desktop and mobile layouts.

4. Optionally, use the availableShippingValues prop in the same layout blocks to define which shipping options to display. If you don't define this prop or set it to an empty array, the system uses the default options: delivery, pickup-in-point, and pickup-nearby. When you provide a non-empty array, it replaces the default entirely and shows only the specified values. Supported values correspond to the search API facet names: delivery, pickup-in-point, pickup-nearby, pickup-all.

   Example with an explicit list (same as the default) plus pickup-all on desktop and mobile:

   
   

   _12

   "search-result-layout.desktop": {

   _12

   "children": ["filter-navigator.v3", "search-content"],

   _12

   "props": {

   _12

   "showShippingMethodFacet": true,

   _12

   "availableShippingValues": [

   _12

   "delivery",

   _12

   "pickup-in-point",

   _12

   "pickup-nearby",

   _12

   "pickup-all"

   _12

   ]

   _12

   }

   _12

   }

   
   

The shipping method facet appears only when showShippingMethodFacet is enabled. If you set availableShippingValues, the component lists those options; otherwise, it falls back to the default. Other Delivery Promise-related facets behave as usual.