Promise

Provide a pre-checkout delivery date to drive conversion rates and reduce customer service calls through clear delivery expectations.

Overview

Promise lets you display accurate delivery date predictions on product pages, at checkout, and in post-purchase communications to improve conversion and customer satisfaction.

You can use parcelLab’s API and self-service Promise configuration in the App to display accurate pre-checkout delivery predictions based on your carriers and warehouses. These predictions are powered by our machine learning algorithm that accounts for distribution setup, holidays, operating hours, weather, and other operational constraints.

Data Requirements

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

Keys for v4 API (new integrations)

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

Keys for v2 API (existing integrations only)

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.

Keys for v4 API (new integrations)

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

Keys for v2 API (existing integrations only)

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 communications, 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

Open

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 details on using the Promise API, please refer to our API documentation:

• v4 API (new integrations)

• v2 API (existing integrations only)

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.

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.

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, 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.

For further information on Promise fulfillment and performance, see our Promise analytics documentation.

Promise Insights