Promise Dates
Use the Promise API to get an estimated delivery date to display during conversion and checkout to reduce uncertainty that leads to cart abandonment and improve customer delivery satisfaction.
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. It can be shown in a format you want on your website so customers can see when a product should arrive before buying it.
Get Promise Date
Details of how the v2/prediction endpoint can be used to generate a forecasted delivery date in the parcelLab system are described below.
Result Structure
The API always returns a list of applicable predictions according to the specified query. The requestId is for tracing and troubleshooting purposes only.
{
"requestId": "abcd1234",
"success": true,
"error": null,
"prediction": [ ... ]
} Each entry in the prediction array represents one delivery method, including a delivery prediction like the following structure:
{
"id": "Delivery Method ID",
"warehouse": "Warehouse ID",
"courier": "parcelLab courier code, e.g. ups",
"courierName": "Pretty courier name",
"courierAlias": "Retailer internal courier code",
"courierServiceLevel": [ "all specified aliases for the service level" ],
"prediction": {
"min": 1,
"max": 2,
"likely": 2,
"send_date": "2022-06-11",
"earliest": "2022-06-12",
"latest": "2022-06-13",
"mostLikely": "2022-06-13",
"earliestLocale": "Thursday, Jun 12th, 2022",
"latestLocale": "Friday, Jun 13th, 2022",
"mostLikelyLocale": "Friday, Jun 13th, 2022",
"cutoff": 747,
"cutoffLocale": "12 hours"
}
} Delivery Prediction Details
The details included in a delivery prediction are described in the following table.
min
Integer
The minimum number of expected courier working days until delivery. Note: The value for minimum and maximum can be equal.
max
Integer
The maximum number of expected courier working days until delivery.
Note: The value for minimum and maximum can be equal.
likely
Integer
The most likely number of expected courier working days until delivery.
earliest
ISO 8601 date format: YYYY-MM-DD
The earliest expected delivery date taking into consideration working days of the courier, holidays in the destination, and warehouse cut-off and handling times.
latest
ISO 8601 date format: YYYY-MM-DD
The latest expected delivery date taking into consideration working days of the courier, holidays in the destination, and warehouse cut-off and handling times.
earliestLocale
Defaults to dddd, MMM DDD, YYYY
Localized representations of the earliest expected delivery date in the specified format.
latestLocale
Defaults to dddd, MMM DDD, YYYY
Localized representations of the latest expected delivery date in the specified format.
mostLikelyLocale
Defaults to dddd, MMM DDD, YYYY
Localized representations of the most likely delivery date in the specified format.
cutoff
Integer
The time in minutes until cut-off for the estimated delivery dates.
cutoffLocale
String
Localized representations of the cut-off. Can be used within a sentence like "Order within [2 hours | an hour | 20 minutes] to receive your order by [Saturday, Mar 23rd, 2022]".
Sample Calls
The sample API calls below show different information in the request (for example: home delivery as the courier service type) for the delivery prediction.
https://api.parcellab.com/v2/prediction?user=1612197&destination=DEU
{
"requestId": "wLy6ThLp",
"success": true,
"prediction": [{
"id": "DHL Standard",
"warehouse": "Europe Warehouse",
"courier": "dhl-germany",
"courierName": "DHL",
"courierAlias": [],
"courierServiceLevel": ["home-delivery","pick-from-store"]
"prediction": {
"min": 1,
"max": 3,
"likely": 2,
"send_date": "2023-11-23",
"earliest": "2023-11-24",
"latest": "2023-11-27",
"mostLikely": "2022-11-25",
"earliestLocale": "Friday, Nov 24th, 2023",
"latestLocale": "Monday, Nov 27th, 2023",
"mostLikelyLocale": "Saturday, Nov 25th, 2023",
"cutoff": 104,
"cutoffLocale": "1 hour, 44 minutes"}},
{
"id": "UPS Express,
"warehouse": "Europe Warehouse",
"courier": "ups",
"courierName": "UPS",
"courierAlias": [],
"courierServiceLevel": ["home-delivery","express","overnight"]
"prediction": {
"min": 1,
"max": 1,
"likely": 1,
"send_date": "2023-11-23",
"earliest": "2023-11-24",
"latest": "2023-11-24",
"mostLikely": "2023-11-24",
"earliestLocale": "Friday, Nov 24th, 2023",
"latestLocale": "Friday, Nov 24th, 2023",
"mostLikelyLocale": "Friday, Nov 24th, 2023",
"cutoff": 76,
"cutoffLocale": "1 hour, 16 minutes"
}
}]
}Calculating Delivery Dates for Orders with Known Dispatch Date
For orders where you know the actual dispatch date, you can calculate accurate delivery dates based on when the order will ship. This is useful for scenarios where:
An order's dispatch date is confirmed after placement
You need to provide customers with updated delivery expectations based on actual shipment dates
Customer service agents need to communicate accurate timelines for existing orders
How It Works
To calculate a delivery date for an already placed order when you know the dispatch date, use these two parameters together:
_now=<date>- set this to the known dispatch date/time in ISO 8601 UTC format (for example:2025-07-01T16:00:00.000Z)dispatchNow=true- this forces the API to skip warehouse cutoff calculations and calculate the delivery date as if the parcel ships at the exact time specified in_now
The _now timestamp must be in UTC (Zulu time), not local time. Always include the Z suffix or .000Z to indicate UTC.
Testing Your Promise Configuration
To preview saved but unpublished changes to your Promise configuration in a staging environment:
Integrate the Promise API call to your staging environment.
Add the query parameter
&draft=trueto your Promise API call.
This will generate a promise date based on your unpublished Promise configuration, that can be used to review the effect of any configuration updates on the frontend of your staging environment.
Last updated
Was this helpful?