This feature is in closed beta, which means that only selected customers can access it. If you are interested in implementing it in the future, please contact our Support team.

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

The availability is displayed following these rules:

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

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

• Shipping Option Components: Used to display a location selector.
• Search Result: Used to implement sidebar filters.

This guide walks you through the basic setup needed to implement these components in your store.

To enable Delivery Promise (Beta) in your store, the following conditions must be met:

• The store must use Intelligent Search.
• Your storefront must be built with Store Framework.
• The store can't act as a marketplace for Seller Portal accounts or external sellers.

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

To use Delivery Promise, customers must define a delivery address early in their shopping journey. The Shipping Option Components app provides blocks that allow users to select a location and display delivery options accordingly.

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

   
   

   _10

   "dependencies": {

   _10

   "vtex.shipping-option-components": "0.x"

   _10

   }

   
   

2. Declare the shipping-option-location-selector block as a child block of your header block, exported by the store-header app. Example:

   
   

   _19

   "header.full": {

   _19

   "blocks": ["header-layout.desktop", "header-layout.mobile"]

   _19

   },

   _19

   _19

   "header-layout.desktop": {

   _19

   "children": [

   _19

   "header-row#1-desktop",

   _19

   ]

   _19

   },

   _19

   _19

   "header-row#1-desktop": {

   _19

   "children": ["shipping-option-location-selector"],

   _19

   },

   _19

   _19

   "shipping-option-location-selector": {

   _19

   "props": {

   _19

   "compactMode": true,

   _19

   }

   _19

   },

   
   

3. Configure the behavior with props to customize how location selection is presented. Below, we highlight some of the key uses of the available props.

   • Setting up a blocking modal
   • Defining displayed delivery methods

   Learn more about all the available props in Shipping Option Components.

When the customer provides their address, an initial selection of products is made to display only products that can be delivered to that location or picked up at pickup points within a radius of up to 50 km from the provided address — a limit determined by the Checkout. This selection impacts all subsequent product listings and filters.

Setting up a blocking model

To ensure location input is provided before browsing, you can configure a blocking modal that displays when the page loads and can't be dismissed until a postal code is entered.

To do this, you must use both the callToAction and dismissible props:

• callToAction: Defines which UI is displayed on load:

  • modal: Displays a modal requiring postal code entry.
  • popover-input (default): Opens a popover with a postal code input field.
  • popover-button: Displays a button that opens the popover when clicked.

• dismissible: When set to false, the modal can't be closed until a valid postal code is entered.

Configure the props as shown in the example below:

This configuration ensures the page is filtered for delivery availability from the first interaction, improving performance and relevance.

Defining displayed delivery methods

The shippingSelection prop controls which delivery methods are displayed:

• delivery-and-pickup: Enables both delivery and pickup location options.
• only-pickup: Displays only the pickup selector (for example, in stores focusing on in-store pickup).

Configure the prop as shown in the example below:

To display available delivery filters in the search sidebar, follow the steps below using the Search Result component. It automatically renders facets, including those related to delivery and pickup availability.

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. Ensure your theme includes the search-result-layout.desktop or search-result-layout.mobile block, depending on the layout.

Within this layout, make sure the sidebar block includes filter-navigator.v3:

These blocks will display all applicable filters automatically. If a customer has selected a location using the Shipping Option component, delivery filters will reflect real-time availability based on that address.

The delivery promise filters are a beta feature and may be subject to breaking changes. If you customize this functionality, ensure your implementation can adapt to updates.