Skip to content
You're viewing the API v4 documentation, recommended for new integrations.
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Promise UI Plugin

Embed delivery estimates on product pages and checkout with the Promise UI widget. Configure IP lookup, destination controls, date display, and styling.

The Promise UI is a standalone JavaScript widget for product pages, carts, and checkout. It displays one delivery method's estimated date or range, with optional carrier, order cutoff, and destination controls.

This is an open-source reference implementation. Use it directly or adapt it for your storefront.

The widget calls GET /v2/prediction, including when you follow this guide in the v4 documentation. Its configuration options are widget options, not v4 query parameters. For a custom frontend using the v4 endpoint, see Promise Dates.

Installation

Use a Promise-enabled account with published warehouses and delivery methods. Replace YOUR_ACCOUNT_ID with your parcelLab account ID and set the country for your customer market. Load one bundle per page.

Create the target element before calling init(). Omit data-promise when you initialize the target yourself.

<div id="delivery-promise"></div>
<script src="https://cdn.parcellab.com/js/promise-ui/v1/promise.iife.js"></script>
<script>
  const widget = window.DeliveryPromise.init({
    target: '#delivery-promise',
    accountId: 'YOUR_ACCOUNT_ID',
    destinationCountry: 'DEU',
    ipFetch: true,
    zipPicker: 'inline',
    countryPicker: true,
    confidence: 'estimated'
  });
</script>

The ESM bundle requires an explicit init() call.

If you know the shopper's delivery address, supply postalCode and destinationCountry, or data-postal-code and data-country. The supplied postal code takes priority over saved choices and IP Fetch. Leave it empty to use a saved choice or an IP estimate.

With IP Fetch enabled and no specified IP, the browser requests the public IP from https://api64.ipify.org, then sends it to parcelLab. If your site uses a Content Security Policy, allow that host and https://api.parcellab.com in connect-src, and the production CDN in script-src.

Live Demo

Preview data and presentation settings, then copy an HTML or JavaScript embed:

Set your account and choose ZIP + country, Country only, or IP Fetch + fallback country. Leave the IP field empty for public-IP lookup, or enter a specific IPv4 or IPv6 address. Presentation presets control layout, date wording, carrier, cutoff, and destination controls.

Sample request shows the configured query. Show API response makes a separate request from the Data controls, so it can differ from a manually corrected widget preview. Enter the same ZIP and country in Data to compare them.

Copy the browser URL to share the controls. Specified IP and ZIP values are included; automatically resolved locations and manual preview corrections are not. The generated embed uses the controls. Use the production bundle URL above when you deploy it. See the product preview guide for the full workflow.

The following examples use the configured country as the fallback for IP requests. Dates, cutoff times, carriers, and locations in the screenshots are examples and depend on the response.

Product Detail Page: Estimate with Cutoff

Show the earliest estimated delivery date and the order cutoff. Hide the carrier and location controls to keep the widget small. The widget still uses the known, saved, resolved, or fallback destination.

Product page estimate with a calendar icon, earliest delivery date, and order cutoff. Location controls are hidden.
A compact delivery estimate for a product detail page.

Checkout: Editable Location and Delivery-by Date

Show the postal code and country from the IP response and let the shopper change them. The location icon marks an approximate location based on IP data or the fallback country. If no postal code is available, the widget shows the country and Add ZIP. Supply the checkout address instead when it is known.

Show the selected delivery method's latest estimated arrival date with "delivery by" wording and the carrier name. Hide the cutoff during checkout.

Replace the three SELECTED_* values below with the configured carrier, service level, and warehouse for the selected checkout shipping option. Initialize the widget only after that option is known. Use filters that identify that method, rather than a list of available methods.

Checkout estimate with a delivery-by date, UPS carrier name, editable ZIP 10013 and United States, and an approximate-location icon.
A checkout delivery estimate with an editable destination.

The product-page example selects the method with the earliest earliest date. The checkout example restricts the request to the selected shipping option and displays its latest date. data-date-mode="by" controls the displayed date; it does not select the shipping option.

For checkout changes, initialize through the JavaScript API with the same settings and retain the returned widget instance. In your checkout's shipping-selection handler, call update() with all three filters together. Here, selectedShippingOption is your checkout's mapping to configured Promise values:

Changing HTML attributes alone does not update an active widget. If the selected option has no matching prediction, omit its delivery date instead of removing the filters to show another method.

Shopper changes through the ZIP or country controls skip further IP lookups. A country change clears the previous ZIP. The widget saves these manual selections for 30 days after the last change and reuses them on later visits when the page supplies no postal code. Public IP values and automatic locations are not saved in browser storage.

Configuration

The tables list the main options. Boolean HTML attributes require the literal value "true" or "false". Use ISO3 country codes such as DEU and USA. The account ID must be a positive integer.

Destination and Request Options

JavaScript option
HTML attribute
Default
Use

target

The element itself

Required in JavaScript

Selector or existing element to receive the widget.

accountId

data-account-id

Required

Your parcelLab account ID.

destinationCountry

data-country

Required

Country for explicit requests and fallback for IP requests.

postalCode

data-postal-code

Empty

Postal code. Takes priority over IP Fetch. Keep leading zeros.

ipFetch

data-ip-fetch

false

Estimate a location if no supplied or saved destination takes priority.

ipAddress

data-ip-address

Empty

Specific IPv4 or IPv6 literal; requires IP Fetch. Otherwise the widget fetches the public IP.

courier

data-courier

Unset

Filter by configured carrier.

serviceLevel

data-service-level

Unset

Filter by configured service level.

warehouse

data-warehouse

Unset

Filter by warehouse.

calibration

data-calibration

Unset

conservative, balanced, or aggressive.

tag

data-tag

Unset

Target configured adjustment rules.

draft

data-draft

false

Use unpublished Promise configuration for testing.

apiBaseUrl

data-api-base-url

https://api.parcellab.com

API origin; the widget still uses the v2 path.

Display Options

JavaScript option
HTML attribute
Default
Use

layout

data-layout

text

text, card, or badge. Badge has no carrier or cutoff text.

dateMode

data-date-mode

from

from, on, by, or range; see date selection below.

dateFormat

data-date-format

long

long, longWithYear, short, shortWithYear, or relative.

confidence

data-confidence

auto

estimated, guaranteed, or auto. Auto uses guaranteed wording for express methods.

showCutoff

data-show-cutoff

auto

auto, always, never, or express-only. Only positive cutoffs are shown.

showCarrier

data-show-carrier

none

none or inline.

icon

data-icon

none

none, truck, or calendar. Card uses a calendar when set to none.

zipPicker

data-zip-picker

none

none hides the location row; inline lets shoppers edit ZIP; link uses the legacy ZIP prompt.

countryPicker

data-country-picker

false

Country selector in the visible location row. A change clears ZIP.

requireZip

data-require-zip

false

Require a ZIP when location controls are visible. IP lookup runs first. Ignored when zipPicker is none.

maxPredictions

data-max-predictions

5

Number of API entries considered for selection.

selectionReferenceDate

data-selection-reference-date

mostLikely

Compare earliest, latest, or mostLikely across methods.

selectionPick

data-selection-pick

earliest

Select the smallest (earliest) or largest (latest) reference date.

fallbackDays

data-fallback-days

Unset

Static business-day estimate when predictions are unavailable. HTML examples: 3 or 2-3.

locale

data-locale

en

Built-in messages: en, de, fr, it, and es.

messages

data-messages

Locale defaults

Partial message overrides; use a JSON object in HTML.

theme

data-theme

Widget defaults

CSS token overrides; use a JSON object in HTML.

className

data-class-name

Unset

Extra class on the widget root.

confidence changes the wording. It does not change the prediction or establish a service guarantee. Use estimated unless your offered service supports a guarantee. The source reference also lists advanced JavaScript-only options.

Select a Method, Then Select Its Displayed Date

First, the widget considers the first maxPredictions results and selects one method using selectionReferenceDate and selectionPick. The request filters limit which methods can appear. At checkout, filter to the shipping option the shopper selected.

Then dateMode chooses which date from that method to display:

Mode
v2 response field in the selected entry
Display

from

prediction.earliest

Earliest estimated arrival.

on

prediction.mostLikely

Most likely arrival.

by

prediction.latest

Delivery-by date.

range

prediction.earliest and prediction.latest

Date range; one date if both match.

For example, selectionReferenceDate: 'latest' with selectionPick: 'earliest' selects the method with the earliest upper date. dateMode: 'by' then displays that upper date. Changing dateMode alone does not change the selected method.

Destination Priority and Persistence

On initialization, the widget uses this order:

  1. A postal code supplied by the page, with its configured country.

  2. An unexpired shopper choice saved in browser storage, including a country-only choice.

  3. IP Fetch, if enabled, using the specified IP or the browser's public IP.

  4. The configured country, if IP Fetch is off or public-IP lookup fails.

For an IP request, destinationCountry becomes fallbackCountry. If the IP location has matching methods, it wins even in another country. Otherwise, the API tries the fallback country without the IP ZIP or region. An empty generated prediction does not trigger another fallback. See the v2 destination contract.

The widget reads location.country and location.zip for the automatic location display. ZIP values of null or "0" leave the editor empty. The approximate-location marker covers both IP lookup and country fallback; the response does not distinguish them. Use the checkout address when it becomes available.

Changes through the ZIP and country controls are saved for 30 days after the last change in the same browser and origin. Reloading does not extend expiry. The storage key is pl-promise-zip, shared by widgets on that origin rather than separated by account. Public IP values and automatic locations are not saved. If storage is blocked, the current choice still works but cannot be reused on later visits. Calls to update() do not write these saved choices.

Widget Instance API

Method
Behavior

widget.update(options)

Merge options, cancel the current request, and render again. Returns a promise.

widget.refresh()

Render with the current destination. Can reuse a cached response. Returns a promise.

widget.destroy()

Cancel the request and remove the rendered widget. Saved choices and shared caches remain.

init() returns immediately and starts loading. Calling it again for the same target updates that instance. To use a different target, create another instance.

When checkout supplies an address, update both fields together:

For a country-only selection, clear the old postal code:

A supplied country clears the automatic location and skips IP Fetch. Presentation-only changes keep it. To return to IP lookup for the current page:

This does not delete a saved manual choice, which can return on reload.

Caching and Order Persistence

Successful responses, including empty results, are cached in memory for the loaded module and shared by its widgets. The cache has no expiry. refresh() does not bypass a matching cached result. The widget does not poll automatically or count down the displayed cutoff. Reloading the page starts a new module cache.

The widget does not save the displayed promise on an order. Its public API also does not expose the selected prediction or response request ID. For checkout persistence, use a custom API integration or extend the reference implementation to retain the response used for display. Save that exact date or range, selected method, confirmed destination, and request ID when the order is placed. See the send/read/save flow and the order field mapping.

Loading, Missing Data, and Errors

State
Display

Loading

Loading message and enabled location controls.

ZIP required but unavailable

ZIP prompt without a date, after IP lookup if enabled.

Matching predictions

One selected method's date or range.

Empty result or HTTP 404

Delivery estimate unavailable, unless fallbackDays is configured. An unresolved IP can first retry with the configured country.

Network failure, other HTTP error, or success: false

Error message, unless fallbackDays is configured.

Static fallback

The host-defined business-day estimate, without carrier or cutoff. It does not replace the ZIP-required prompt.

Enabled location controls remain available for correction. A country fallback supplies a destination; fallbackDays supplies a static estimate. A static estimate is not an API prediction.

Styling and Localization

The widget renders in the light DOM and injects its default styles once per page. It inherits your page typography. Use theme to change supported colors and radius, or target the .pl-promise root and its element classes with CSS.

Add these options to your initialization configuration:

For example, override root tokens on a widget mounted in #delivery-promise:

Useful element classes include .pl-promise__summary-date, .pl-promise__deliver-to, .pl-promise__cutoff-line, .pl-promise__card, and .pl-promise__badge. See the full styling reference for supported tokens and classes.

Messages are built in for English, German, French, Italian, and Spanish. Other locales use English UI messages. Dates and country names use the supplied locale through the browser's Intl APIs. ZIP editing, country selection, and the approximate-location marker have accessible labels.

Source Code

The reference implementation uses the MIT license.

Last updated

Was this helpful?