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.

This guide details how to use the Delivery Promise feature on headless stores, using the Intelligent Search API with additional facets.

Only products that can be delivered to the provided address or picked up at pickup points are displayed, following these rules:

• The system displays all available pickup points within the 50 km radius configured in Checkout. This applies when the customer selects pickup in the header or a specific pickup point. There’s no limit to the number of pickup points displayed.

• For the nearby pickup filter, the system displays pickup points within a 10 km radius of the buyer's location, up to 40 pickup points.

• Make sure you have Intelligent Search installed, namely admin-search and search-resolver. Learn more in Installing Intelligent Search.
• Complete Catalog integration with Intelligent Search. Learn more in Starting the integration with Catalog.

The GET Get list of products for a query endpoint from Intelligent Search API accepts path parameters referred to as facets:

To enable the Delivery Promise functionality, you should use the following additional query strings and facets on this request. We recommend using query strings when possible for better performance.

Facet	Description	Example
zip-code [required]	Postal code. It can also be used as a query string.	Query string: ?zip-code=22250040&coordinates=-43.18218231201172,-22.94549560546875 Facet: /zip-code/22250040/coordinates/-43.18218231201172,-22.94549560546875
coordinates [required]	Address coordinates. To get the coordinates based on a postal code, follow the steps in Get address by postal code to return the coordinates in the correct and expected value inside the geoCoordinates object. It can also be used as a query string.	Query string: ?zip-code=22250040&coordinates=-43.18218231201172,-22.94549560546875 Facet: /zip-code/22250040/coordinates/-43.18218231201172,-22.94549560546875
shipping	Shipping method. It must always be combined with zip-code and coordinates. Possible values: pickup-in-point delivery pickup-all pickup-nearby	/zip-code/22250040/coordinates/-43.18218231201172,-22.94549560546875/shipping/pickup-in-point/
pickupPoint	Pickup point ID to filter by a specific pickup point. This is used only with the shipping/pickup-in-point facet, besides the required parameters. It can also be used as a query string.	Query string: /shipping/pickup-in-point?zip-code=22250040&coordinates=-43.18218231201172,-22.94549560546875&pickupPoint=vtex-botafogo Facet: /zip-code/22250040/coordinates/-43.18218231201172,-22.94549560546875/shipping/pickup-in-point/pickupPoint/vtex-botafogo

zip-code and coordinates are required to filter product availability based on the shopper’s location and are integral to any request using Delivery Promise. You must use them when filtering by shipping method and pickup point.

Here is an example of a basic Delivery Promise search using only postal code and coordinates, which are the required facets:

To filter the search by a shipping method, you must use the shipping parameter and some additional optional parameters, depending on the type of filter you want to implement.

The possible filters are:

• Delivery to the shopper’s postal code
• Pickup at a specific location
• Pickup at a nearby location

Learn more about each of them in the following sections.

Delivery to the shopper’s ZIP code

Filters the search for products that can be delivered to the postal code entered by the buyer.

Parameters: /shipping/delivery

Example:

Pickup at a specific location

Filters the search for products that can be picked up at a specific pickup point selected by the buyer.

Parameters: /shipping/pickup-in-point/pickupPoint/{pickupPointId}

To first fetch the list of pickup points for the store, follow the List pickup points by location guide and API reference.

Example:

Pickup at a nearby location

Filters the search for products that can be picked up at pickup points located within a radius of up to 50 km from the shopper, within the same pickup radius limit as the Checkout.

Parameters: /shipping/pickup-in-point/pickup-nearby

Example:

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.

In headless implementations, you must manually retrieve and render filters using the VTEX Intelligent Search APIs — for example, in a filter sidebar where users can refine results by shipping method or pickup location.

You can retrieve available filters using the GET Get facets endpoint and use the response to build a custom filter UI in your headless storefront. For example, mapping name: "pickup-in-point" to a checkbox labeled Pickup in store.

Delivery-related filters (for example, delivery and pickup-in-point) are included in the facets response. These are tied to the user's session and shipping context (segment token). Make sure the segment and shipping data are initialized correctly for this to work.

Example request:

Example response: