This feature is in closed beta, which means that only selected customers can access it for now. 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 Intelligent Search API with additional facets for this purpose.

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. To enable this functionality, you must fetch the complete list of pickup points using the Checkout API. Retrieving this list is a mandatory dependency for the Delivery Promise feature in headless stores.
• For the nearby pickup filter, pickup points within a 10 km radius of the buyer's location are shown.

• Make sure you have Intelligent Search installed, namely admin-search and search-resolver. Learn more at Installing Intelligent Search.
• Complete Catalog integration with Intelligent Search. Learn more at 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. When possible, using query strings is recommended for better performance.

Query string / Facet	Description	Example
zip-code [required] (query string)	Postal code.	?zip-code=22250040
shipping (facet)	Shipping method. It must always be combined with zip-code. Possible values: pickup-in-point, delivery, pickup-all, pickup-nearby	/shipping/pickup-in-point/?zip-code=22250040
pickupPoint (query string)	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.	/shipping/pickup-in-point?zip-code=22250040&pickupPoint=vtex-botafogo
delivery-options (facet)	Delivery Option ID or IDs to be filtered. The ID can be obtained in the VTEX Admin, at Shipping > Delivery Options. It must always be combined with zip-code. Multiple entries of this filter can be used in the request to search for multiple Delivery Options.	/delivery-options/express-option-id?zip-code=22250040
dynamic-estimate (facet)	The Dynamic Estimate filter selects Delivery Options that can meet the requested delivery or pickup timeframe. It must always be used together with zip-code and shipping. Possible values: same-day, next-day. It dynamically identifies which Delivery Options for the given zip-code and shipping facet can meet the requested timeframe, and then filters the search as if those Delivery Options had been manually passed as filters.	/shipping/delivery/dynamic-estimate/same-day?zip-code=22250040
hideUnavailableItems (query string)	Controls whether the search returns only available products or both available and unavailable ones. When set to true, only products with stock are returned; when set to false, the API includes unavailable products as well. A product is considered unavailable when availableQuantity = 0, while availableQuantity = 10000 indicates that the product is available. When filtering by shipping method (shipping), Delivery Options (delivery-options), or Dynamic Estimates (dynamic-estimate), this parameter must be set to true. Otherwise, products that are unavailable for the selected filter may be displayed. When filtering only by ZIP code (zip-code) without any of the above filters, retailers may choose to show unavailable items for commercial reasons (for example, to signal that they carry those products even if temporarily out of stock). This facet also allows merchants to expose a shopper-facing filter such as "show only in-stock products." If hideUnavailableItems is omitted, products with the ShowIfNotAvailable property set to true in the Catalog may appear even if unavailable. Learn more about the ShowIfNotAvailable property in the Catalog API reference.	?hideUnavailableItems=true

For stores using Delivery Promise, the zip-code parameter is mandatory in all Intelligent Search API requests to filter product availability according to the shopper's location. This applies to both Product Listing Pages (PLP) and Product Detail Pages (PDP), and is integral to any request using Delivery Promise functionality, including when filtering by shipping method and pickup point.

For stores not using Delivery Promise, the zip-code parameter is not required and can be omitted from Intelligent Search API requests.

When filtering by shipping method (shipping), Delivery Options (delivery-options), or Dynamic Estimates (dynamic-estimate), you must include the hideUnavailableItems=true query parameter in your requests. If this parameter is omitted, the search engine will include products with the ShowIfNotAvailable property set to true in the Catalog module even if they are not available for the selected filter. For example, product 649553 may appear in results if it has ShowIfNotAvailable enabled, unless you explicitly set hideUnavailableItems=true. Learn more about the ShowIfNotAvailable property in the Catalog API reference.

For more information on facet options apart from the ones directly related to Delivery Promise, go to GET Get list of products for a query.

When shoppers apply filters, the API combines them according to the following rules:

• Facets of the same type → OR (union): when multiple values of the same facet are applied, the API returns the union of all products matching any of those values.
• Facets of different types → AND (intersection): when different facet types are combined, the API returns only the products that satisfy all selected facet conditions simultaneously.

This results in the following behavior when using Delivery Options and Dynamic Estimates:

• Multiple Delivery Options → OR (union): the API returns all products that match any of the delivery options selected by the shopper.
• Dynamic Estimate + Delivery Option → AND (intersection): the API returns only the products that satisfy both the selected dynamic estimate and the chosen delivery option.

Here is an example of a basic Delivery Promise search using only postal code:

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 ZIP 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 zip 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}

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-nearby

Example:

To retrieve the list of available pickup points with their IDs, distances, addresses, and business hours, use the GET Get pickup point availability endpoint from Intelligent Search API. This endpoint returns pickup points based on product availability (product cluster/collection), sorted by distance from the provided coordinates.

You can call this endpoint in two ways:

• With country and ZIP code: Provide the country and ZIP code to retrieve pickup points based on location.

  
  

  _10

  GET https://api.vtexcommercestable.com.br/api/intelligent-search/v0/pickup-point-availability/productClusterIds/{productClusterIds}/trade-policy/{tradePolicy}?zip-code={zipCode}&an={accountName}&coordinates={coordinates}&country={country}

  
  

• With delivery zones and pickups hashes: Alternatively, provide pre-computed hashes (deliveryZonesHash and pickupsHash) for faster lookup.

  
  

  _10

  GET https://api.vtexcommercestable.com.br/api/intelligent-search/v0/pickup-point-availability/productClusterIds/{productClusterIds}/trade-policy/{tradePolicy}?deliveryZonesHash={deliveryZonesHash}&pickupsHash={pickupsHash}&an={accountName}

  
  

Delivery Options are the set of choices a merchant provides to shoppers, describing how and when an order can be delivered, along with relevant metadata such as estimated delivery time.

Before you can display Delivery Option filters, it is necessary to:

• Enable the Delivery Options feature by contacting our Support.
• Create the Delivery Options for your store in the VTEX Admin following the instructions in the Delivery Options guide.

To filter by a Delivery Option, use the delivery-options parameter. Its value must be the ID for one of the Delivery Options configured on your store.

Example:

You can also filter for multiple Delivery Options by including multiple entries for the delivery-options parameter on the request.

Example:

Dynamic Estimates for the delivery or pickup of a product are computed in real-time when searching. They are based on the store’s logistics operations, time of day and any product properties that might affect them. The possible values are Same-day Delivery and Next-day Delivery.

To filter by a Dynamic Estimate, you must use the dynamic-estimate parameter.

Same-day Delivery

Filters the search for products that can be delivered or picked up at the provided zip-code on the same day.

Example:

Next-day Delivery

Filters the search for products that can be delivered or picked up at the provided zip-code on the next day.

Example:

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

In headless implementations, you must manually retrieve and render filters using VTEX Intelligent Search APIs. For example, inside a filter sidebar, where you want users to refine results based on 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 (e.g. delivery, 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:

To ensure consistent Delivery Promise information between Product Listing Pages (PLP) and Product Detail Pages (PDP), you must use the Intelligent Search API for both. Using different APIs (such as Catalog API for PDP and Intelligent Search for PLP) may result in inconsistent delivery information.

When implementing Product Detail Pages (PDP) in headless stores using Delivery Promise, use the Intelligent Search API to ensure:

• Consistent delivery information: Delivery estimates and availability shown on the PLP match those on the PDP.
• Accurate pickup point data: Pickup points and their availability remain consistent across the shopping experience.
• Real-time availability: Product availability is always calculated based on the shopper's location.

To retrieve a specific product with Delivery Promise data for the PDP, use the GET Get list of products for a query endpoint with the query (or q) parameter using specific product or SKU identifiers.

The Intelligent Search API supports the following ID types in the query parameter:

Search by Product ID:

Search by SKU ID:

Search by SKU EAN:

Search by SKU Reference ID:

Search by product slug (linkText):

Examples:

When implementing PDP with Delivery Promise:

• query or q (required): Use one of the supported ID formats: product:{id}, product.id:{id}, sku:{id}, sku.id:{id}, sku.ean:{ean}, sku.reference:{refId}, or product.link:{slug}.
• zip-code (required): Must be included to ensure accurate delivery estimates and product availability.