# Promise Dates ## 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. {% hint style="info" %} For more information on the scope and requirements of this feature, please contact your parcelLab representative. {% endhint %} ## Get Promise Date You can retrieve the forecasted delivery date of an order using the `v4/promise/prediction/predict` endpoint. ## GET /v4/promise/prediction/predict/ > Generate prediction ```json {"openapi":"3.1.0","info":{"title":"parcelLab API","version":"v4"},"security":[{"OAuth2 Authentication":[]},{"HeaderToken":[]}],"components":{"securitySchemes":{"OAuth2 Authentication":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"HeaderToken":{"type":"http","scheme":"bearer","bearerFormat":"Parcellab-API-Token base64(account_id:token)","description":"Send `Authorization: Parcellab-API-Token `.\n\n`` = `base64(account_id:token)` as provided in the portal."}},"schemas":{"PredictionResponse":{"properties":{"request_id":{"title":"Request Id","type":"string"},"success":{"title":"Success","type":"boolean"},"prediction":{"items":{"$ref":"#/components/schemas/Prediction"},"title":"Prediction","type":"array"}},"required":["request_id","success","prediction"],"title":"PredictionResponse","type":"object"},"Prediction":{"properties":{"id":{"description":"Delivery Method ID","title":"Id","type":"string"},"warehouse":{"description":"Warehouse ID","title":"Warehouse","type":"string"},"courier":{"description":"parcelLab courier code, e.g. ups","title":"Courier","type":"string"},"courier_name":{"description":"Pretty courier name","title":"Courier Name","type":"string"},"courier_alias":{"description":"Retailer internal courier code","items":{"type":"string"},"title":"Courier Alias","type":"array"},"courier_service_level":{"description":"All specified aliases for the service level","items":{"type":"string"},"title":"Courier Service Level","type":"array"},"prediction":{"$ref":"#/components/schemas/PredictionDetails","description":"The prediction details"}},"required":["id","warehouse","courier","courier_name","courier_alias","courier_service_level","prediction"],"title":"Prediction","type":"object"},"PredictionDetails":{"properties":{"min":{"description":"The minimum number of expected courier working days until delivery. Note: The value for minimum and maximum can be equal.","title":"Min","type":"integer"},"max":{"description":"The maximum number of expected courier working days until delivery. Note: The value for minimum and maximum can be equal.","title":"Max","type":"integer"},"likely":{"description":"The most likely number of expected courier working days until delivery.","title":"Likely","type":"integer"},"send_date":{"description":"The date of dispatch as per warehouse configuration.","format":"date","title":"Send Date","type":"string"},"earliest_date":{"description":"The earliest expected delivery date taking into consideration working days of the courier, holidays in the destination, and warehouse cut-off and handling times.","format":"date","title":"Earliest Date","type":"string"},"latest_date":{"description":"The latest expected delivery date taking into consideration working days of the courier, holidays in the destination, and warehouse cut-off and handling times.","format":"date","title":"Latest Date","type":"string"},"most_likely_date":{"description":"The most likely individual date of delivery.","format":"date","title":"Most Likely Date","type":"string"},"earliest_locale":{"description":"Localized representations of the earliest expected delivery date in the specified format.","title":"Earliest Locale","type":"string"},"latest_locale":{"description":"Localized representations of the latest expected delivery date in the specified format.","title":"Latest Locale","type":"string"},"most_likely_locale":{"description":"Localized representations of the most likely delivery date in the specified format.","title":"Most Likely Locale","type":"string"},"cutoff":{"description":"The time in minutes until cut-off for the estimated delivery dates.","title":"Cutoff","type":"integer"},"cutoff_locale":{"description":"Localized representation of the cut-off time.","title":"Cutoff Locale","type":"string"}},"required":["min","max","likely","send_date","earliest_date","latest_date","most_likely_date","earliest_locale","latest_locale","most_likely_locale","cutoff","cutoff_locale"],"title":"PredictionDetails","type":"object"},"Error400Response":{"type":"object","properties":{"type":{"type":"string"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/GenericErrorItem"}}},"required":["errors","type"]},"GenericErrorItem":{"type":"object","properties":{"code":{"type":"string"},"detail":{"type":"string"},"attr":{"type":["string","null"]}},"required":["code","detail"]}}},"paths":{"/v4/promise/prediction/predict/":{"get":{"operationId":"promise_prediction_predict_retrieve","summary":"Generate prediction","parameters":[{"in":"query","name":"account","schema":{"type":"integer","title":"Account ID"},"description":"Account ID","required":true},{"in":"query","name":"calibration","schema":{"enum":["conservative","balanced","aggressive",null],"type":["string","null"]},"description":"Set to true, to indicate that the prediction should be done based on the current, not yet published, promise configuration\n\n* `conservative` - conservative\n* `balanced` - balanced\n* `aggressive` - aggressive"},{"in":"query","name":"courier","schema":{"type":["string","null"],"minLength":1,"maxLength":40},"description":"The logistics courier to be used. Defaults to returning all configured couriers."},{"in":"query","name":"destination_country_iso3","schema":{"type":"string"},"description":"ISO 3166-1 alpha-3 code of destination country","required":true},{"in":"query","name":"destination_postal_code","schema":{"type":["string","null"],"minLength":1,"maxLength":10},"description":"Postal code of destination"},{"in":"query","name":"dispatch_now","schema":{"type":"boolean","default":false},"description":"Forces the forecasted delivery date to skip any warehouse calculation and generate a prediction if the parcel is shipped at the moment of the API call, if set to 'true'"},{"in":"query","name":"draft","schema":{"type":["boolean","null"],"title":"Draft Mode"},"description":"Set to true, to indicate that the prediction should be done based on the current, not yet published, promise configuration"},{"in":"query","name":"language_iso2","schema":{"type":["string","null"],"minLength":2,"maxLength":2},"description":"ISO 639-1 code of the language to use for localization"},{"in":"query","name":"now_override","schema":{"type":["string","null"],"format":"date-time","title":"Now"},"description":"Locks the prediction for a specified request date as a ISO 8601 date and time in UTC format like 2022-06-10T06:42:00Z. Defaults now to the current time if omitted, which is required for production usage. "},{"in":"query","name":"service_level","schema":{"type":["string","null"],"minLength":1,"maxLength":40},"description":"The courier service level mapped in your Promise configuration (for example: express delivery). Defaults to returning all courier service levels."},{"in":"query","name":"tag","schema":{"type":["string","null"],"minLength":1,"maxLength":40},"description":"Tag to target prediction adjustment rule"},{"in":"query","name":"warehouse","schema":{"type":["string","null"],"minLength":1,"maxLength":40},"description":"The warehouse the delivery shipped from (input field: key). Defaults to the default warehouse for the destination."}],"tags":["Promise"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PredictionResponse"}}},"description":""},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error400Response"}}},"description":""}}}}}} ``` ### Result Structure The API always returns a list of applicable predictions according to the specified query. The `request_id` is for tracing and troubleshooting purposes only. 
{ 
    "request_id": "abcd1234", 
    "success": true,
    "error": null, 
    "prediction": [ ... ] 
}
Each entry in the prediction array represents one delivery method, including a delivery prediction like the following structure: ```json { "id": "Delivery Method ID", "warehouse": "Warehouse ID", "courier": "parcelLab courier code, e.g. ups", "courier_name": "Pretty courier name", "courier_alias": [ "Retailer internal courier code" ], "courier_service_level": [ "all specified aliases for the service level" ], "prediction": { "min": 1, "max": 2, "likely": 2, "send_date": "2022-06-11", "earliest_date": "2022-06-12", "latest_date": "2022-06-13", "most_likely_date": "2022-06-13", "earliest_locale": "Thursday, Jun 12th, 2022", "latest_locale": "Friday, Jun 13th, 2022", "most_likely_locale": " Friday, Jun 13th, 2022", "cutoff": 747, "cutoff_locale": "12 hours" } } ``` #### Delivery Prediction Details The details included in a delivery prediction are described in the following table.
KeyTypeDescription
minIntegerThe minimum number of expected courier working days until delivery.
Note: The value for minimum and maximum can be equal.
maxInteger

The maximum number of expected courier working days until delivery.

Note: The value for minimum and maximum can be equal.

likelyIntegerThe most likely number of expected courier working days until delivery.
send_dateISO 8601 date format: YYYY-MM-DDThe date of dispatch as per warehouse configuration.
earliest_dateISO 8601 date format: YYYY-MM-DDThe earliest expected delivery date taking into consideration working days of the courier, holidays in the destination, and warehouse cut-off and handling times.
latest_dateISO 8601 date format: YYYY-MM-DDThe latest expected delivery date taking into consideration working days of the courier, holidays in the destination, and warehouse cut-off and handling times.
most_likely_dateISO 8601 date format: YYYY-MM-DDThe most likely individual date of delivery.
earliest_localeDefaults to dddd, MMM DDD, YYYYLocalized representations of the earliest expected delivery date in the specified format.
latest_localeDefaults to dddd, MMM DDD, YYYYLocalized representations of the latest expected delivery date in the specified format.
most_likely_localeDefaults to dddd, MMM DDD, YYYYLocalized representations of the most likely delivery date in the specified format.
cutoffIntegerThe time in minutes until cut-off for the estimated delivery dates.
cutoff_localeStringLocalized 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. {% tabs %} {% tab title="Country" %} {% code overflow="wrap" %} ```json https://api.parcellab.com/v4/promise/prediction/predict?account=1612197&destination_country_iso3=DEU { "requestId": "wLy6ThLp", "success": true, "prediction": [{ "id": "DHL Standard", "warehouse": "Europe Warehouse", "courier": "dhl-germany", "courier_name": "DHL", "courier_alias": [], "courier_service_level": ["home-delivery","pick-from-store"] "prediction": { "min": 1, "max": 3, "likely": 2, "send_date": "2023-11-23", "earliest_date": "2023-11-24", "latest_date": "2023-11-27", "most_likely_date": "2022-11-25", "earliest_locale": "Friday, Nov 24th, 2023", "latest_locale": "Monday, Nov 27th, 2023", "most_likely_locale": "Saturday, Nov 25th, 2023", "cutoff": 104, "cutoff_locale": "1 hour, 44 minutes"}, { "id": "UPS Express, "warehouse": "Europe Warehouse", "courier": "ups", "courier_name": "UPS", "courier_alias": [], "courier_service_level": ["home-delivery","express","overnight"] "prediction": { "min": 1, "max": 1, "likely": 1, "send_date": "2023-11-23", "earliest_date": "2023-11-24", "latestdate: "2023-11-24", "most_likely_date": "2023-11-24", "earliest_locale": "Friday, Nov 24th, 2023", "latest_locale": "Friday, Nov 24th, 2023", "most_likely_locale": "Friday, Nov 24th, 2023", "cutoff": 76, "cutoff_locale": "1 hour, 16 minutes" } }] } ``` {% endcode %} {% endtab %} {% tab title="Country and Zip Code" %} {% code overflow="wrap" %} ```json https://api.parcellab.com/v4/promise/prediction/predict?account=1612197&destination_country_iso3=DEU&destination_postal_code=80469 { "requestId": "Zgr8YN3w", "success": true, "prediction": [{ "id": "DHL Standard", "warehouse": "Europe Warehouse", "courier": "dhl-germany", "courier_name": "DHL", "courier_alias": [], "courier_service_level": ["home-delivery","pick-from-store"] "prediction": { "min": 1, "max": 3, "likely": 2, "send_date": "2023-11-23", "earliest_date": "2023-11-24", "latest_date": "2023-11-27", "most_likely_date": "2023-11-25", "earliest_locale": "Friday, Nov 24th, 2023", "latest_locale": "Monday, Nov 27th, 2023", "most_likely_locale": "Saturday, Nov 25th, 2023", "cutoff": 104, "cutoff_locale": "1 hour, 44 minutes"}, { "id": "UPS Express, "warehouse": "Europe Warehouse", "courier": "ups", "courier_name": "UPS", "courier_alias": [], "courier_service_level": ["home-delivery","express","overnight"] "prediction": { "min": 1, "max": 1, "likely": 1, "send_date": "2023-11-23", "earliest_date": "2023-11-24", "latest_date": "2023-11-24", "most_likely_date": "2022-11-24", "earliest_locale": "Friday, Nov 24th, 2023", "latest_locale": " Friday, Nov 24th, 2023", "most_likely_locale": "Friday, Nov 24th, 2023", "cutoff": 76, "cutoff_locale": "1 hour, 16 minutes" } }] } ``` {% endcode %} {% endtab %} {% tab title="Specific Service Types" %} {% code overflow="wrap" %} ```json https://api.parcellab.com/v4/promise/prediction/predict?account=1612197&destination_country_iso3=USA&service_level=home-delivery { "requestId": "gxFAiZfP", "success": true, "prediction": [{ "id": "USPS Standard", "warehouse": "US East Coast Warehouse", "courier": "usps", "courier_name": "USPS", "courier_alias": [], "courier_service_level": ["home-delivery","pick-from-store"] "prediction": { "min": 3, "max": 5, "likely": 4, "send_date": "2022-08-19", "earliest_date": "2022-08-24", "latest_date": "2022-08-26", "most_likely_date": "2022-08-25", "earliest_locale": "Wednesday, Aug 24th, 2022", "latest_locale": "Friday, Aug 26th, 2022", "most_likely_locale": "Thursday, Aug 25th, 2022", "cutoff": 1236, "cutoff_locale": "21 hours" } }] } ``` {% endcode %} {% endtab %} {% endtabs %} ### 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: 1. `now_override=` - set this to the known dispatch date/time in ISO 8601 UTC format (for example: `2025-07-01T16:00:00.000Z`) 2. `dispatch_now=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_override` {% hint style="warning" %} The `now_override` timestamp must be in UTC (Zulu time), not local time. Always include the `Z` suffix or `.000Z` to indicate UTC. {% endhint %} {% hint style="info" %} When using `dispatch_now=true` with a specific `now_override` value for already placed orders, the `cutoff` will be 0 as you're bypassing warehouse calculations and calculating delivery based on the known dispatch time. {% endhint %} ### Testing Your Promise Configuration To preview saved but unpublished changes to your Promise configuration in a staging environment: 1. Integrate the Promise API call to your staging environment. 2. Add the query parameter `&draft=true` to 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.parcellab.com/docs/developers/promise/api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.