EDU-17285 - Delivery Promise Badges (Store Framework)

[barbara-celi]

Summary

EDU-17285

---

Type of change

• New content — Adds new documentation.
• Content update — Improves existing documentation (clarity, structure, examples, accuracy).
• Bug fix — Fixes markdown issues.
• Editorial fix — Spelling, grammar, or minor copy edits that don’t change meaning.
• Content removal — Deletes deprecated or obsolete content.

---

Checklist

• The content follows the VTEX Style Guide.
• Markdown renders correctly (headings, lists, tables, callouts).
• Links, images, code blocks, and examples are valid.
• Terminology, product names, and API references are consistent.
• Frontmatter (title, description, tags, slug) is correct
• Files follow the expected folder structure and naming conventions.

---

AI review instructions

This repository supports automated AI reviews for Markdown files in the docs folder, except docs/localization.

To run reviews on this PR, add at least one of the following labels:

• AI style review: evaluates tone and adherence to VTEX style guidelines.
• AI grammar review: identifies grammar and spelling issues.

Once at least one label is added, the review(s) will run automatically.

After the review is completed, the corresponding label will be removed and the label AI reviewed will be added to the PR.

Note

To rerun a review, remove and add the desired label again.

[github-actions]

👁️‍🗨️ Preview changes on Developer Portal

You can use the link below to load the Developer Portal in preview mode with the changes from this branch:

👉 Open preview environment

Below is the list of modified pages and their corresponding preview URLs:

File	Preview URL	Sidebar
docs/guides/Search/setting-up-delivery-promise-components.md	https://developers.vtex.com/docs/guides/setting-up-delivery-promise-components	✅ Listed

[github-actions]

Remaining comments which cannot be posted as a review comment to avoid GitHub Rate Limit

markdownlint

---

[markdownlint] _{reported by reviewdog 🐶}
MD029/ol-prefix Ordered list item prefix [Expected: 2; Actual: 4; Style: 1/2/3]

dev-portal-content/docs/guides/Search/setting-up-delivery-promise-components.md

Line 217 in 0ac10af

4. Optionally, define which shipping options should be displayed using the `availableShippingValues` prop in the same layout blocks. When this prop is not defined, or when it is set to an empty array, the default options are used: `delivery`, `pickup-in-point`, and `pickup-nearby`. When you provide a non-empty array, it replaces the default entirely, and only the specified values are shown. Supported values correspond to the search API facet names and include: `delivery`, `pickup-in-point`, `pickup-nearby`, `pickup-all`.

[github-actions]

✏️ Grammar review summary

docs/guides/Search/setting-up-delivery-promise-components.md

Corrected spacing issues after blockquote markers, fixed word order for 'subsequent', corrected the preposition 'in shelves' to 'on shelves', and removed unnecessary definite articles.

---

Was this feedback useful?

• Yes
• No

Review made on commit 0ac10af

[github-actions]

🔍 Documentation feedback for docs/guides/Search/setting-up-delivery-promise-components.md

This review evaluates the Setting up Delivery Promise components (Beta) guide against the specified rules for VTEX Developer Portal documentation.

1. General Feedback

The guide is well-structured and provides clear technical instructions. However, it deviates from the rules in three main areas:

• Frontmatter: The excerpt field is empty, but the rules require a concise one-sentence summary.
• Step Headings: The headings use gerunds (e.g., "Requesting", "Displaying") instead of the required imperative form (e.g., "Request", "Display").
• Instruction Lists (Rule R2.5): Several numbered steps begin with introductory phrases, adverbs, or dependent clauses rather than starting immediately with an imperative verb.

---

2. Actionable Feedback

• Frontmatter: Fill the excerpt field with a one-sentence summary of the guide's goal.
• Step Headings:
  • Change Step 1 - Requesting... to Step 1 - Request....
  • Change Step 2 - Displaying... to Step 2 - Display....
  • Change Step 3 - Implementing... to Step 3 - Implement....
  • Change Step 4 - Displaying... to Step 4 - Display....
• Numbered Lists (Rule R2.5):
  • Step 3, Item 1: Remove "In your theme's manifest.json," and start the sentence with "Add".
  • Step 3, Item 4: Remove "Optionally," and start the sentence with "Define".
  • Step 4, Item 1: Remove the introductory clause "Since you have already added..." and start the sentence with "Declare".

---

3. Suggested Revision

---
title: "Setting up Delivery Promise components (Beta)"
slug: "setting-up-delivery-promise-components"
excerpt: "Learn how to configure and display Delivery Promise components in your Store Framework storefront."
hidden: false
createdAt: "2025-05-23T22:18:24.684Z"
updatedAt: "2026-06-02T17:03:26.293Z"
seeAlso:
 - "/docs/apps/vtex.delivery-promise-components"
---

> ℹ️ 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](https://support.vtex.com/hc/en-us) team.

The [Delivery Promise (Beta)](https://help.vtex.com/en/tutorial/delivery-promise-beta--p9EJH9GgxL0JceA6dBswd) 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.

>ℹ️ Delivery Promise supports any seller architecture (franchise accounts, VTEX Sellers, [Seller Portal](https://help.vtex.com/en/tracks/vtex-store-overview--eSDNk26pdvemF3XKM0nK9/4yPqZQyj0t675QpcG7H6yl#vtex-account-types), and external sellers).

![delivery-promise-components](https://vtexhelp.vtexassets.com/assets/docs/src/shipping-option-components___c5a1d86b0ebf692a3eb9ca49f79b55f8.png)

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

* [Delivery Promise Components](https://developers.vtex.com/docs/apps/vtex.delivery-promise-components): Used to display blocks for postal code, delivery versus pickup, and pickup point selection.
* [Search Result](https://developers.vtex.com/docs/apps/vtex.search-result): Used to implement sidebar filters.

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

>ℹ️ Explore the [Delivery Promise Figma library](https://www.figma.com/community/file/1545494767147168145/delivery-promise-by-vtex) to learn more about component specs, usage guidelines, reference use cases, and behavioral patterns.

## Before you begin

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

* The store must use [Intelligent Search](https://help.vtex.com/en/tracks/vtex-intelligent-search--19wrbB7nEQcmwzDPl1l4Cb/3qgT47zY08biLP3d5os3DG).
* Check if you have installed the `0.5.0` or a later version of the [`search-session`](https://developers.vtex.com/docs/apps/vtex.search-session) app. 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](https://help.vtex.com/en/tracks/vtex-store-overview--eSDNk26pdvemF3XKM0nK9/67SCtUreXxKYWhZh8n0zvZ#store-framework) to enable the components in this guide. If you use FastStore, check the [FastStore Delivery Promise implementation guide](https://developers.vtex.com/docs/guides/faststore/delivery-promise-implementation). If your store is headless, check [Delivery Promise for headless stores](https://developers.vtex.com/docs/guides/delivery-promise-for-headless-stores).

## Instructions

### Step 1 - Request Delivery Promise activation

1. Contact our [Support](https://support.vtex.com/hc/en-us) team to request the activation of Delivery Promise.

### Step 2 - Display a location selector

To use Delivery Promise, customers must provide a delivery address early in their shopping journey. The [`delivery-promise-components`](https://developers.vtex.com/docs/apps/vtex.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:

   ```json
      "dependencies": {
        "vtex.delivery-promise-components": "1.x"
      }
   ```

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 a location is set. |
| `pickup-point-selector`    | Optional. A control for choosing which pickup point to use after a location is set.  |

3. Configure the behavior with props to customize the blocks. Below are the available props.

#### `shopper-location-setter`

| Prop                         | Type      | Default     | Description                                                                                                            |
| ---------------------------- | --------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
| `required`                   | `boolean` | `false`     | When `true`, opens a non-dismissible postal code modal until a valid code is set. 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 cannot be dismissed until a method is selected (after a postal code is entered). |
| `mode`     | `string`  | `"default"` | Display mode: `default` or `icon`.                                                                                |

#### `pickup-point-selector`

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

### Step 3 - Implement sidebar filters

To display Delivery Promise filters in the search sidebar, configure the [Search Result](https://developers.vtex.com/docs/apps/vtex.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. Add the `search-result` app to your theme's `manifest.json` as a dependency:

   ```json
    "dependencies": {
        "vtex.search-result": "3.x"
    }
   ```

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

3. Enable the Delivery Promise filters by setting the `showShippingMethodFacet` to `true` in each flexible search layout where the facet should appear. This property is disabled by default, so the shipping method filter remains hidden unless explicitly enabled.

4. Define which shipping options should be displayed using the `availableShippingValues` prop in the same layout blocks. When this prop is not defined, or when it is set to an empty array, the default options are used: `delivery`, `pickup-in-point`, and `pickup-nearby`. When you provide a non-empty array, it replaces the default entirely, and only the specified values are shown. Supported values correspond to the search API facet names and include: `delivery`, `pickup-in-point`, `pickup-nearby`, `pickup-all`.

### Step 4 - Display availability badges on product shelves

To display availability badges on product cards in shelves and search results, configure the [Availability Badges](https://developers.vtex.com/docs/apps/vtex.delivery-promise-components/AvailabilityBadges) component as follows. These badges show delivery and pickup availability for each product based on the buyer's location.

1. Declare the `availability-badges` block as a child in your product summary component.

**Example**

```json mark=6
"product-summary.shelf": {
  "children": [
    "product-summary-image",
    "product-summary-name",
    "product-summary-price",
    "availability-badges", // Add this block
    "add-to-cart-button"
  ]
}
```

The `availability-badges` block automatically displays badges when Delivery Promise data is available, helping shoppers quickly identify which products can be shipped to their address or picked up at nearby stores.

> ℹ️ The badges are hidden when no postal code is set or when Delivery Promise data is unavailable for the product. This ensures a clean interface when the information cannot be determined.

---

Was this feedback useful?

• Yes
• No

Review made on commit 0ac10af

[github-actions]

[link-check] _{reported by reviewdog 🐶}
🚨 Found a broken link in a Markdown Link (Error 404):
https://www.figma.com/community/file/1545494767147168145/delivery-promise-by-vtex

👉 Please review this link before merging your Pull Request.

[github-actions]

[markdownlint] _{reported by reviewdog 🐶}
MD051/link-fragments Link fragments should be valid [Context: "step 2"]