Predict Checkout EDD
Creates a checkout event — a virtual representation of a potential order — and returns its Estimated Delivery Date. One checkout event corresponds to at most one resulting Shipment; checkout events are not visible in the Portal.
Minimum input: from_address and to_address, each with
country_code (preferred) or country. The more you provide (postal
codes, carrier references, shipping service, merchant), the better the
prediction.
One EDD per carrier: the response’s data array carries one entry
— its own checkout_id and checkout_edd — per carrier_reference
value sent (or a single entry with carrier_reference: null when none
was sent). When the order confirms, send the selected carrier’s
checkout_id back in additional_info.checkout_id on Create Shipment
— linking works at creation only, and both links are permanent and
one-to-one.
How the EDD is calculated: the calculation starts from
order_target_time (or the request time), applies your account’s
warehouse processing rules where configured (operating hours, cut-off,
carrier pick-up, peak buffers), picks the model matching your
configuration (carrier, corridor, day of week, handling instructions),
turns the model’s daily delivery probabilities into a date or range via
configured confidence thresholds, and adds the days as business days
for the destination country (weekends and public holidays skipped by
default).
Validation is all-or-nothing: if any part of the request is
invalid, no checkout event is created and no checkout_id is issued.
curl --request POST \
--url https://api.perform.ai/v1/edd/checkout/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"carrier_reference": [
"dhl-ecommerce-de"
],
"shipping_service": [
"standard"
],
"merchant_id": "501",
"order_target_time": "2026-09-22T10:30:00",
"order_target_timezone": "Asia/Singapore",
"to_address": {
"country_code": "SG",
"postal_code": "049145",
"city": "Singapore",
"first_name": "Jane",
"last_name": "Doe"
},
"from_address": {
"country_code": "DE",
"postal_code": "10115",
"city": "Berlin",
"company": "Example Store Warehouse"
},
"shipment_value": "135.50 SGD",
"item_count": 2,
"line_items": [
{
"product_name": "Classic Running Shoes",
"product_id": "SKU-RUN-01",
"quantity": 1,
"product_weight": 230,
"product_weight_unit": "g",
"currency_code": "SGD",
"product_cost": 99.99
}
],
"prediction_payload": {
"handling_instructions": "Paket",
"warehouse_ref": "SG-01"
}
}
'import requests
url = "https://api.perform.ai/v1/edd/checkout/"
payload = {
"carrier_reference": ["dhl-ecommerce-de"],
"shipping_service": ["standard"],
"merchant_id": "501",
"order_target_time": "2026-09-22T10:30:00",
"order_target_timezone": "Asia/Singapore",
"to_address": {
"country_code": "SG",
"postal_code": "049145",
"city": "Singapore",
"first_name": "Jane",
"last_name": "Doe"
},
"from_address": {
"country_code": "DE",
"postal_code": "10115",
"city": "Berlin",
"company": "Example Store Warehouse"
},
"shipment_value": "135.50 SGD",
"item_count": 2,
"line_items": [
{
"product_name": "Classic Running Shoes",
"product_id": "SKU-RUN-01",
"quantity": 1,
"product_weight": 230,
"product_weight_unit": "g",
"currency_code": "SGD",
"product_cost": 99.99
}
],
"prediction_payload": {
"handling_instructions": "Paket",
"warehouse_ref": "SG-01"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
carrier_reference: ['dhl-ecommerce-de'],
shipping_service: ['standard'],
merchant_id: '501',
order_target_time: '2026-09-22T10:30:00',
order_target_timezone: 'Asia/Singapore',
to_address: {
country_code: 'SG',
postal_code: '049145',
city: 'Singapore',
first_name: 'Jane',
last_name: 'Doe'
},
from_address: {
country_code: 'DE',
postal_code: '10115',
city: 'Berlin',
company: 'Example Store Warehouse'
},
shipment_value: '135.50 SGD',
item_count: 2,
line_items: [
{
product_name: 'Classic Running Shoes',
product_id: 'SKU-RUN-01',
quantity: 1,
product_weight: 230,
product_weight_unit: 'g',
currency_code: 'SGD',
product_cost: 99.99
}
],
prediction_payload: {handling_instructions: 'Paket', warehouse_ref: 'SG-01'}
})
};
fetch('https://api.perform.ai/v1/edd/checkout/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.perform.ai/v1/edd/checkout/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'carrier_reference' => [
'dhl-ecommerce-de'
],
'shipping_service' => [
'standard'
],
'merchant_id' => '501',
'order_target_time' => '2026-09-22T10:30:00',
'order_target_timezone' => 'Asia/Singapore',
'to_address' => [
'country_code' => 'SG',
'postal_code' => '049145',
'city' => 'Singapore',
'first_name' => 'Jane',
'last_name' => 'Doe'
],
'from_address' => [
'country_code' => 'DE',
'postal_code' => '10115',
'city' => 'Berlin',
'company' => 'Example Store Warehouse'
],
'shipment_value' => '135.50 SGD',
'item_count' => 2,
'line_items' => [
[
'product_name' => 'Classic Running Shoes',
'product_id' => 'SKU-RUN-01',
'quantity' => 1,
'product_weight' => 230,
'product_weight_unit' => 'g',
'currency_code' => 'SGD',
'product_cost' => 99.99
]
],
'prediction_payload' => [
'handling_instructions' => 'Paket',
'warehouse_ref' => 'SG-01'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.perform.ai/v1/edd/checkout/"
payload := strings.NewReader("{\n \"carrier_reference\": [\n \"dhl-ecommerce-de\"\n ],\n \"shipping_service\": [\n \"standard\"\n ],\n \"merchant_id\": \"501\",\n \"order_target_time\": \"2026-09-22T10:30:00\",\n \"order_target_timezone\": \"Asia/Singapore\",\n \"to_address\": {\n \"country_code\": \"SG\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\"\n },\n \"from_address\": {\n \"country_code\": \"DE\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"company\": \"Example Store Warehouse\"\n },\n \"shipment_value\": \"135.50 SGD\",\n \"item_count\": 2,\n \"line_items\": [\n {\n \"product_name\": \"Classic Running Shoes\",\n \"product_id\": \"SKU-RUN-01\",\n \"quantity\": 1,\n \"product_weight\": 230,\n \"product_weight_unit\": \"g\",\n \"currency_code\": \"SGD\",\n \"product_cost\": 99.99\n }\n ],\n \"prediction_payload\": {\n \"handling_instructions\": \"Paket\",\n \"warehouse_ref\": \"SG-01\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.perform.ai/v1/edd/checkout/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"carrier_reference\": [\n \"dhl-ecommerce-de\"\n ],\n \"shipping_service\": [\n \"standard\"\n ],\n \"merchant_id\": \"501\",\n \"order_target_time\": \"2026-09-22T10:30:00\",\n \"order_target_timezone\": \"Asia/Singapore\",\n \"to_address\": {\n \"country_code\": \"SG\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\"\n },\n \"from_address\": {\n \"country_code\": \"DE\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"company\": \"Example Store Warehouse\"\n },\n \"shipment_value\": \"135.50 SGD\",\n \"item_count\": 2,\n \"line_items\": [\n {\n \"product_name\": \"Classic Running Shoes\",\n \"product_id\": \"SKU-RUN-01\",\n \"quantity\": 1,\n \"product_weight\": 230,\n \"product_weight_unit\": \"g\",\n \"currency_code\": \"SGD\",\n \"product_cost\": 99.99\n }\n ],\n \"prediction_payload\": {\n \"handling_instructions\": \"Paket\",\n \"warehouse_ref\": \"SG-01\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.perform.ai/v1/edd/checkout/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"carrier_reference\": [\n \"dhl-ecommerce-de\"\n ],\n \"shipping_service\": [\n \"standard\"\n ],\n \"merchant_id\": \"501\",\n \"order_target_time\": \"2026-09-22T10:30:00\",\n \"order_target_timezone\": \"Asia/Singapore\",\n \"to_address\": {\n \"country_code\": \"SG\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\"\n },\n \"from_address\": {\n \"country_code\": \"DE\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"company\": \"Example Store Warehouse\"\n },\n \"shipment_value\": \"135.50 SGD\",\n \"item_count\": 2,\n \"line_items\": [\n {\n \"product_name\": \"Classic Running Shoes\",\n \"product_id\": \"SKU-RUN-01\",\n \"quantity\": 1,\n \"product_weight\": 230,\n \"product_weight_unit\": \"g\",\n \"currency_code\": \"SGD\",\n \"product_cost\": 99.99\n }\n ],\n \"prediction_payload\": {\n \"handling_instructions\": \"Paket\",\n \"warehouse_ref\": \"SG-01\"\n }\n}"
response = http.request(request)
puts response.read_bodyAuthorizations
The same Bearer token as the Public API v5 — generate it with POST /auth/oauth/token/.
Body
Origin (from_address) or destination (to_address) of the potential shipment. country_code (preferred) or country is required; city and postal code markedly improve predictions. Fields other than country and postal code are stored with the checkout event and forwarded to the model — they are not normalized and not carried over to the Shipment.
Show child attributes
Show child attributes
Origin (from_address) or destination (to_address) of the potential shipment. country_code (preferred) or country is required; city and postal code markedly improve predictions. Fields other than country and postal code are stored with the checkout event and forwarded to the model — they are not normalized and not carried over to the Shipment.
Show child attributes
Show child attributes
Carrier references from Settings > Carriers — a non-empty list even for a single value (an empty list is rejected). One EDD entry is returned per value, so you can compare carriers in one call. An unconfigured value rejects the whole request. Used only for the prediction — send carrier_reference again at Create Shipment.
1 - 50 elements1 - 50The carrier's service level (e.g. standard, express) — a list even for a single value. Only one of carrier_reference and shipping_service may contain more than one value in the same request.
50Identifier of the merchant/supplier on your platform. Strongly recommended for marketplaces — fulfillment speed varies by merchant.
50The order time to calculate the EDD from; defaults to the time the request is received. Send a local wall-clock time (YYYY-MM-DDThh:mm:ss, no offset) and name the zone in order_target_timezone. With an offset or Z, the value is first normalized to UTC and that wall-clock time is then interpreted in order_target_timezone.
IANA timezone of order_target_time. Defaults to UTC; invalid IDs are rejected.
50100100Total value of the items as <number> <CURRENCY> with a valid ISO 4217 code, e.g. 35.50 SGD. Values without the space, or with extra characters, are rejected.
50Start of a delivery window you already promised, if any. Use this field alone for a single expected date. ISO 8601; read as UTC without an offset.
Requires expected_delivery_from. ISO 8601.
Items at the checkout stage. NOT carried over to a created Shipment.
Show child attributes
Show child attributes
Extra model inputs agreed with the Perform.AI data team during your POC. Three keys are also read by the platform when selecting your model and fulfillment rules — handling_instructions (parcel type/handling class, e.g. Paket; required for some models), warehouse_ref (your warehouse identifier, selects processing-time rules), and carrier_service (carrier service code for fulfillment rules). A key must not appear both here and at the top level of the request — that is rejected.
Response
Prediction generated — one data entry per requested carrier reference, each with its own checkout_id.
curl --request POST \
--url https://api.perform.ai/v1/edd/checkout/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"carrier_reference": [
"dhl-ecommerce-de"
],
"shipping_service": [
"standard"
],
"merchant_id": "501",
"order_target_time": "2026-09-22T10:30:00",
"order_target_timezone": "Asia/Singapore",
"to_address": {
"country_code": "SG",
"postal_code": "049145",
"city": "Singapore",
"first_name": "Jane",
"last_name": "Doe"
},
"from_address": {
"country_code": "DE",
"postal_code": "10115",
"city": "Berlin",
"company": "Example Store Warehouse"
},
"shipment_value": "135.50 SGD",
"item_count": 2,
"line_items": [
{
"product_name": "Classic Running Shoes",
"product_id": "SKU-RUN-01",
"quantity": 1,
"product_weight": 230,
"product_weight_unit": "g",
"currency_code": "SGD",
"product_cost": 99.99
}
],
"prediction_payload": {
"handling_instructions": "Paket",
"warehouse_ref": "SG-01"
}
}
'import requests
url = "https://api.perform.ai/v1/edd/checkout/"
payload = {
"carrier_reference": ["dhl-ecommerce-de"],
"shipping_service": ["standard"],
"merchant_id": "501",
"order_target_time": "2026-09-22T10:30:00",
"order_target_timezone": "Asia/Singapore",
"to_address": {
"country_code": "SG",
"postal_code": "049145",
"city": "Singapore",
"first_name": "Jane",
"last_name": "Doe"
},
"from_address": {
"country_code": "DE",
"postal_code": "10115",
"city": "Berlin",
"company": "Example Store Warehouse"
},
"shipment_value": "135.50 SGD",
"item_count": 2,
"line_items": [
{
"product_name": "Classic Running Shoes",
"product_id": "SKU-RUN-01",
"quantity": 1,
"product_weight": 230,
"product_weight_unit": "g",
"currency_code": "SGD",
"product_cost": 99.99
}
],
"prediction_payload": {
"handling_instructions": "Paket",
"warehouse_ref": "SG-01"
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
carrier_reference: ['dhl-ecommerce-de'],
shipping_service: ['standard'],
merchant_id: '501',
order_target_time: '2026-09-22T10:30:00',
order_target_timezone: 'Asia/Singapore',
to_address: {
country_code: 'SG',
postal_code: '049145',
city: 'Singapore',
first_name: 'Jane',
last_name: 'Doe'
},
from_address: {
country_code: 'DE',
postal_code: '10115',
city: 'Berlin',
company: 'Example Store Warehouse'
},
shipment_value: '135.50 SGD',
item_count: 2,
line_items: [
{
product_name: 'Classic Running Shoes',
product_id: 'SKU-RUN-01',
quantity: 1,
product_weight: 230,
product_weight_unit: 'g',
currency_code: 'SGD',
product_cost: 99.99
}
],
prediction_payload: {handling_instructions: 'Paket', warehouse_ref: 'SG-01'}
})
};
fetch('https://api.perform.ai/v1/edd/checkout/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.perform.ai/v1/edd/checkout/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'carrier_reference' => [
'dhl-ecommerce-de'
],
'shipping_service' => [
'standard'
],
'merchant_id' => '501',
'order_target_time' => '2026-09-22T10:30:00',
'order_target_timezone' => 'Asia/Singapore',
'to_address' => [
'country_code' => 'SG',
'postal_code' => '049145',
'city' => 'Singapore',
'first_name' => 'Jane',
'last_name' => 'Doe'
],
'from_address' => [
'country_code' => 'DE',
'postal_code' => '10115',
'city' => 'Berlin',
'company' => 'Example Store Warehouse'
],
'shipment_value' => '135.50 SGD',
'item_count' => 2,
'line_items' => [
[
'product_name' => 'Classic Running Shoes',
'product_id' => 'SKU-RUN-01',
'quantity' => 1,
'product_weight' => 230,
'product_weight_unit' => 'g',
'currency_code' => 'SGD',
'product_cost' => 99.99
]
],
'prediction_payload' => [
'handling_instructions' => 'Paket',
'warehouse_ref' => 'SG-01'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.perform.ai/v1/edd/checkout/"
payload := strings.NewReader("{\n \"carrier_reference\": [\n \"dhl-ecommerce-de\"\n ],\n \"shipping_service\": [\n \"standard\"\n ],\n \"merchant_id\": \"501\",\n \"order_target_time\": \"2026-09-22T10:30:00\",\n \"order_target_timezone\": \"Asia/Singapore\",\n \"to_address\": {\n \"country_code\": \"SG\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\"\n },\n \"from_address\": {\n \"country_code\": \"DE\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"company\": \"Example Store Warehouse\"\n },\n \"shipment_value\": \"135.50 SGD\",\n \"item_count\": 2,\n \"line_items\": [\n {\n \"product_name\": \"Classic Running Shoes\",\n \"product_id\": \"SKU-RUN-01\",\n \"quantity\": 1,\n \"product_weight\": 230,\n \"product_weight_unit\": \"g\",\n \"currency_code\": \"SGD\",\n \"product_cost\": 99.99\n }\n ],\n \"prediction_payload\": {\n \"handling_instructions\": \"Paket\",\n \"warehouse_ref\": \"SG-01\"\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.perform.ai/v1/edd/checkout/")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"carrier_reference\": [\n \"dhl-ecommerce-de\"\n ],\n \"shipping_service\": [\n \"standard\"\n ],\n \"merchant_id\": \"501\",\n \"order_target_time\": \"2026-09-22T10:30:00\",\n \"order_target_timezone\": \"Asia/Singapore\",\n \"to_address\": {\n \"country_code\": \"SG\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\"\n },\n \"from_address\": {\n \"country_code\": \"DE\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"company\": \"Example Store Warehouse\"\n },\n \"shipment_value\": \"135.50 SGD\",\n \"item_count\": 2,\n \"line_items\": [\n {\n \"product_name\": \"Classic Running Shoes\",\n \"product_id\": \"SKU-RUN-01\",\n \"quantity\": 1,\n \"product_weight\": 230,\n \"product_weight_unit\": \"g\",\n \"currency_code\": \"SGD\",\n \"product_cost\": 99.99\n }\n ],\n \"prediction_payload\": {\n \"handling_instructions\": \"Paket\",\n \"warehouse_ref\": \"SG-01\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.perform.ai/v1/edd/checkout/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"carrier_reference\": [\n \"dhl-ecommerce-de\"\n ],\n \"shipping_service\": [\n \"standard\"\n ],\n \"merchant_id\": \"501\",\n \"order_target_time\": \"2026-09-22T10:30:00\",\n \"order_target_timezone\": \"Asia/Singapore\",\n \"to_address\": {\n \"country_code\": \"SG\",\n \"postal_code\": \"049145\",\n \"city\": \"Singapore\",\n \"first_name\": \"Jane\",\n \"last_name\": \"Doe\"\n },\n \"from_address\": {\n \"country_code\": \"DE\",\n \"postal_code\": \"10115\",\n \"city\": \"Berlin\",\n \"company\": \"Example Store Warehouse\"\n },\n \"shipment_value\": \"135.50 SGD\",\n \"item_count\": 2,\n \"line_items\": [\n {\n \"product_name\": \"Classic Running Shoes\",\n \"product_id\": \"SKU-RUN-01\",\n \"quantity\": 1,\n \"product_weight\": 230,\n \"product_weight_unit\": \"g\",\n \"currency_code\": \"SGD\",\n \"product_cost\": 99.99\n }\n ],\n \"prediction_payload\": {\n \"handling_instructions\": \"Paket\",\n \"warehouse_ref\": \"SG-01\"\n }\n}"
response = http.request(request)
puts response.read_body