> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout EDD Widget

> Embeddable component that shows an estimated delivery date on your product, cart, checkout and order confirmation pages, in your design and language.

**Available to all Checkout customers.**

## Summary

The Checkout EDD Widget is an embeddable HTML and JavaScript component that displays a Perform.AI-calculated estimated delivery date (EDD) on your storefront. You add it to a page with two lines of code; it calls Perform.AI when the page loads, renders the date in your branding and language, and recalculates as the shopper changes where the parcel is going.

## Who it’s for

E-commerce and front-end teams who want a single delivery date on every page where a shopper decides to buy, without building and maintaining the display themselves. The widget suits brands that would rather insert a snippet than build a feature; brands that want full control over rendering call the Checkout EDD API instead and get the same prediction without the component.

## Key benefits

* **One date across the journey.** The same prediction appears on product, cart, checkout and order confirmation pages, and the checkout reference carries it into the order confirmation email and the Tracking Page.
* **Set up once, place anywhere.** Each page gets a variant and a two-line snippet. The widget works on any page you can insert HTML into, and on Shopify’s locked checkout, thank-you and order status pages through a Perform.AI Custom App.
* **Reads as part of your store.** Layout, colours, fonts, icons and copy are configured to your design, with one variant per language and no cap on the number of languages.
* **A shopper can change the destination.** The Standard version carries a country and postal code selector, and the date recalculates in real time.
* **Never an error, never an empty space.** When no confident date can be produced, the shopper sees a short text range instead.

## How it works

### Versions

| Version | Shopper can change location? | Typical use |
| - | - | - |
| Standard | Yes. Country and postal code selector; the EDD recalculates in real time | Product and cart pages, where no address is known yet |
| Lean | No. Uses fixed default location values | Pages where the address is already known, or where a simpler display is preferred |

The widget is responsive down to a 600 px breakpoint, loads asynchronously and shows a skeleton loader while the date is fetched, so the page does not block on it.

### Where it can be placed

The widget is a standard embeddable script and can sit on any page where you can insert HTML, provided the page can supply or default the location inputs described below.

| Page | Non-Shopify storefronts | Shopify |
| - | - | - |
| Product page | Two-line embed | Custom Liquid (all plans) |
| Cart page | Two-line embed | Custom Liquid (all plans) |
| Checkout page | Two-line embed | Shopify Plus only, through a Perform.AI Custom App using Checkout UI Extensions |
| Thank You and Order Status pages | Two-line embed | Custom App (all plans except Starter) |
| Any other page | Two-line embed | Custom Liquid, where the theme allows it |

Shopify does not permit arbitrary customisation of its checkout and post-purchase pages, so those pages need a Custom App built with Shopify’s own UI components. One Custom App covers one Shopify Organization: all stores in that Organization can use it, and a separate Organization needs a separate app.

### Variants

A variant is a configured combination of layout, language, shipping method and page type, and the snippet selects it by `data-variant-id`.

* **One variant per page type.** Use the variant issued for that page; a product-page variant placed on a cart or checkout page will not behave correctly.
* **One variant per language.** Multilingual storefronts use one variant per language. Translations of the widget’s fixed elements (the “Estimated Delivery Date” label, the fallback text, the error message in the location selector) are maintained by Perform.AI and further languages can be added on request. Any surrounding copy you add is yours and must be supplied per language.
* **One variant per shipping method.** Standard and Express produce different dates for the same destination, so each shipping method you want to show is its own variant. On product and cart pages, where the shopper has not chosen a method yet, the variant you place decides which method is estimated: Express shows the fastest date early in the journey, Standard shows the date most shoppers get. If the product page shows Express and the shopper then selects Standard at checkout, the date changes between the pages. Your account team confirms the choice during onboarding and can change it later on request.

### Installation

Copy the snippet for each funnel stage from the Domains page (see [Set up in the portal](#set-up-in-the-portal)). It has the shape:

```html theme={null}
<div data-variant-id="b9f5b625-d08b-460d-b3a3-2d3e83fc0f00" class="pp-checkout-widgets"></div>
<script type="module" src="SCRIPT_URL_FROM_THE_DOMAINS_PAGE"></script>
```

The script URL is shown on the Domains page with your snippet; copy it from there.

The `<script>` tag loads the widget runtime and `data-variant-id` selects which variant is rendered. You receive a test variant first, then deploy to production.

If the widget is placed somewhere the page re-renders (a cart drawer, a mini-cart, a single-page checkout step), re-run it after the update:

```javascript theme={null}
window.__pp_widgetController__.rerun(variantId)
```

This is the usual fix when the widget renders on first load but disappears or goes stale after a cart change.

### Location inputs

The widget needs a destination and, where you ship from more than one location, an origin. It resolves these in strict priority order, falling through to the next source only when the previous one is unavailable:

1. Values already on the page, such as the address fields on your checkout page or a saved profile address.
2. Values the shopper enters in the widget’s own location selector.
3. Browser information (geolocation and timezone), which triggers a browser permission prompt.
4. Local storage: context or cookies carried over from earlier pages.
5. A default value you provide, as the final fallback.

No single input is strictly mandatory, because every input has a configured default, so the widget always renders something. Accuracy drops quietly as you supply less: the practical minimum for a real date is a destination country code, and the destination postal code is the single biggest accuracy gain over country alone. Origin country and postal code matter where you ship from more than one location.

| Page | Destination | Origin |
| - | - | - |
| Product page | Usually not known. The Standard widget’s selector collects it from the shopper, or you supply a default for the storefront’s market | Supply if you ship from more than one location |
| Cart page | Same as the product page | Same as the product page |
| Checkout page | Point the widget at your address fields. The shopper has entered a real address, so this is the highest-value step of the integration | Supply if multi-origin |
| Thank You and Order Status pages | Point at the confirmed order address, or supply fixed values | Supply if multi-origin |

The Standard widget’s location selector offers a fixed set of countries. That list governs what a shopper can pick in the selector and is separate from the destinations your EDD model covers; confirm the markets in scope with your account team.

### Fallback behaviour

When an EDD cannot be calculated, because the destination falls outside the configured model scope, no postal code has been resolved yet, or the prediction does not meet the required confidence threshold, the widget shows a fallback text range instead of a date.

* It is a text range, not a date. The shopper sees a range expressed in words.
* It defaults to “2-3 business days” and can be adjusted on request to reflect typical transit times in your main market.
* It is translated along with the rest of the widget’s fixed elements.

If the fallback appears more often than expected, it usually means a lane not yet covered by your model scope or destination inputs not reaching the widget. Both are resolvable with your account team.

### What the shopper sees

A calculated date is rendered in the format **Days to Delivery, Date Month (Day of Delivery)**, where the first part is Today, Tomorrow or the number of days:

* *Tomorrow, 13 October (Monday)*
* *In 3 days, 15 October (Wednesday)*

### The checkout reference and storing dates

The widget returns a `checkout_id` in its page response. It does not expose the predicted dates as retrievable values.

The `checkout_id` is a reference key. To link the date shown at checkout to a real order, pass it in the `additional_info` object when you create the shipment:

```json theme={null}
"additional_info": {
  "checkout_id": "f631b0c3-30f4-4b07-9ee6-64553e102a0c",
  "checkout_time": "2023-12-21T01:00:10"
}
```

Once linked, the checkout EDD for that order is visible when you retrieve the shipment, and the same date can be used in the order confirmation email and on the Tracking Page. See [Shipment EDD](https://developers.perform.ai/products/checkout/shipment-edd.md).

On Shopify checkout, Thank You and Order Status pages the `checkout_id` is written to an order metafield rather than being readable from the page; query it with the Shopify Admin GraphQL API.&#x20;

If you need the dates themselves in your own systems, the widget alone will not do this:

| Option | How it works | Trade-off |
| - | - | - |
| Widget and API | The widget renders the date; you call the Checkout EDD API separately to retrieve and store the value | Two calls; the stored value is guaranteed and there is no rendering work on your side |
| API only | You call the API, store the result and render the date yourself | One call and full control over presentation; you build and maintain the UI |

Serving the displayed date from the widget while independently calling the API can, in principle, produce two values if the model updates between calls. The API-only option avoids this.

### Configuration and changes

The widget’s design is configured to your branding, but all configuration and updates are made by Perform.AI. There is no self-service design editor. To change layout, copy, translations, default values or positioning, raise a request with your account team and include the desired design. Because a Shopify Custom App can only be tested inside your own store, final verification on production sits with you.

## Set up in the portal

Widget-to-page assignment and the implementation snippets live on the Domains page. Domains are created by Perform.AI at your request; select **Add Domain** to raise the request.

Go to **Checkout** > **Domains**.

1. Select the domain’s row to open its detail panel.
2. Select the pencil icon, choose a widget for each funnel stage you want to cover (Product, Cart, Checkout, Thank You) and select **Save**.
3. Select **Widget Implementation** and copy the snippet for each stage. Each snippet contains its own `data-variant-id` and the widget script.
4. Add each snippet to the matching storefront page. Changing an assignment changes the `data-variant-id`, so the storefront must be updated for the change to take effect.

> [!TIP]
>
> Assign a widget to all four stages where possible. A Thank You page widget is the only way completed orders can be attributed to checkout sessions in [Checkout Analytics](https://developers.perform.ai/products/checkout/checkout-analytics.md).

For Shopify checkout, Thank You and Order Status pages, Perform.AI supplies a custom install link. Install the app in your Shopify admin, then add the app block in the Checkout Editor (**Settings** > **Checkout** > **Customize**) on the Shipping step and on the Thank you page, and save. Installing the app does not by itself make the widget appear; the app block step is the one most often missed. If the widget appears in standard checkout but not in Shop Pay, approve the app in the checkout authorization prompt. See [Shopify integration](https://developers.perform.ai/integrations/shopify.md).

## Use via API and MCP

* Guide: [Predict checkout delivery dates](https://developers.perform.ai/guides/predict-checkout-edd.md) shows how to request a prediction, display it and link the `checkout_id` to the shipment.
* API reference: [Predict checkout EDD](https://developers.perform.ai/api-reference/checkout/predict-checkout-edd.md).
* MCP: `list_checkout_domains` returns your domains and their widget assignments; `list_checkout_variants` returns the configured widget variants. Both are documented on [MCP tools](https://developers.perform.ai/mcp/tools.md).

## FAQ

### Which fields do I have to add to my pages?

None are strictly mandatory, but accuracy depends on them. A destination country code is the practical minimum for a real date, and pointing the widget at your checkout address fields is the highest-value step.

### Do the required fields differ per page?

The fields are the same; what changes is where the values come from. On product and cart pages the widget’s own selector usually supplies the destination; on the checkout page you point it at your address fields.

### Can I put the widget somewhere other than product, cart or checkout?

Yes. It works on any page where you can insert HTML, as long as that page can supply or default the location inputs. Widgets on custom pages such as mini-cart drawers sit outside the four funnel stages and are not counted in Checkout Analytics.

### Why does the widget show a range like “2-3 business days” instead of a date?

That is the fallback, shown when a confident date cannot be produced for that destination. Persistent fallback usually means a lane outside your model scope or inputs not reaching the widget.

### Why is the date on my product page different from the one at checkout?

Most often the two pages estimate different shipping methods: the product-page variant may be Express while the shopper selected Standard at checkout. Choose the product-page variant deliberately.

### Can I change the widget design myself?

Not currently. Raise a change request with your account team. If you want direct control over rendering, call the Checkout EDD API and build your own front end.

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| The widget disappears or goes stale after the cart updates | The page re-rendered the element holding the widget | Call `window.__pp_widgetController__.rerun(variantId)` after the update. |
| The fallback range shows on most sessions | The destination is outside the model scope, or destination inputs are not reaching the widget | Check the inputs the page supplies, then confirm the lanes in scope with your account team. |
| The widget behaves incorrectly on a page | The variant placed was issued for a different page type | Use the variant issued for that page, copied from the Domains page. |
| The widget does not appear on the Shopify checkout page | The app block was not added in the Checkout Editor, the store is not on Shopify Plus, or the app has not been approved for Shop Pay | Add the app block under **Settings** > **Checkout** > **Customize**; confirm the plan; approve the app in the checkout authorization prompt. |
| A shopper is asked for location permission | The input chain fell through to browser information | Supply the destination on the page or set a default, so the widget resolves it earlier in the chain. |

## Related

* [EDD Prediction Model](https://developers.perform.ai/products/checkout/edd-prediction-model.md)
* [Checkout Analytics](https://developers.perform.ai/products/checkout/checkout-analytics.md)
* [Checkout Widget A/B Testing](https://developers.perform.ai/products/checkout/checkout-widget-ab-testing.md)
* [Pick-Up Point Selector](https://developers.perform.ai/products/checkout/pick-up-point-selector.md)
* [Shipment EDD](https://developers.perform.ai/products/checkout/shipment-edd.md)
* [Checkout overview](https://developers.perform.ai/products/checkout/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.