Using Promise

Display a promise date to your customers during conversion and at checkout and include it in your post-purchase communication.

Overview

parcelLab provides an API you can call to get forecasted delivery dates. This date can be used to display a delivery date promise on the product details page or at checkout.

For details on using the Promise API, please refer to the API documentation:

Data Requirements

To use Promise, the following keys need to be sent to parcelLab in tracking records for Track & Communicate. This ensures the data is available to reference in your Promise configuration.

Key	Type	Description
courierServiceLevel	String	Product or service level from carrier.
warehouse	String	Warehouse from which the delivery was shipped.

To display the generated promise date in communications, the following keys need to be sent to parcelLab when creating a tracking.

Key	Type	Description
announced_delivery_date	Date	The predicted delivery date that is generated using parcelLab Promise and displayed to the customer at checkout.
customFields	String	Custom field where the key-value pair is the request ID of the API call (for example: requestID: "gxFAiZfP").

For further details on how to send parcelLab the promise date for use in Track & Communicate, refer to the section Using Promise Dates in Communications from parcelLab.

For a list of input fields required to configure Promise in the App (that is: Service Levels, Warehouses and Delivery Methods), refer to the Promise Configuration Template.

21KB

Promise Configuration Template.xlsx

Displaying Promise on Your Website

The following sections describe the recommended process for integrating parcelLab Promise into your online shop and using the generated promise date in your post-purchase communications.

Call the Promise API

After publishing your Promise configuration in the App, you can retrieve promise dates by calling the Promise API.

For further details, refer to the Promise API page.

Best Practices for Displaying Promise

This section provides an overview of ways to display promise dates and recommendations for where to display them.

The potential inputs that can be used from your customers to generate a forecasted delivery date are described in the following table.

Input	Accuracy	Use
Zip Code	This is the most accurate input for the model to generate a promise.	There are two ways to use a zip code input: Add a snippet to capture the customer’s desired shipping postal code. Pull this from the customer’s profile.
Country	This is not the most precise input but still provides a good estimate for shoppers.	Pull this from the browsing country.

You can choose to display the promise date as one of the following:

• Single date (January 1, 2023)

• Date range (January 1-3)

Promise dates can be displayed on product landing pages or product detail pages.

Promise date displayed on a product detail page

Promise date displayed at checkout

Using Promise Dates in Communications from parcelLab

This section describes the recommended flow for integrating Promise into your website and post-purchase communication, including the following key points:

• Calling the Promise API at checkout

• Transmitting Promise data back to parcelLab for sending order and delivery notifications using Track & Communicate.

You can calculate accurate delivery dates for orders with a known dispatch date by using the _now and _dispatchNow parameters together to bypass warehouse cutoff logic and estimate delivery based on the exact shipment time. For further details, refer to the Promise API page.

When displaying a promise date at checkout, we recommend the following procedure:

1. Call the Promise API at checkout.

2. Display a promise date to the shopper based on your desired business outcome (for example: displaying the earliest date to push conversion).

3. Save the displayed date against the customer’s order.

If possible, save both the displayed promise date and requestID from the API response.

To ensure continuity when using Track & Communicate, we recommend:

1. Using the promise date generated by parcelLab as the announced delivery date (announced_delivery_date key) when creating an order or creating a tracking record.

2. Including the requestID of the API call as a custom field.

This ensures that parcelLab can correctly measure whether the promise date is met and enables troubleshooting any issues that arise.

The reporting on Promise fulfillment can be viewed in the Insights section of the Promise module in the App.