> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Predict checkout delivery dates

> Show accurate delivery estimates at checkout, and link each prediction to the shipment it becomes.

`POST /v1/edd/checkout/` creates a **checkout event** — a virtual representation of a potential order — and returns an Estimated Delivery Date from your tailored machine-learning model or a generic model configured for your fulfillment timelines. Use it to show delivery estimates on product, cart, and checkout pages. Full field specs: [API reference](/api-reference/checkout/predict-checkout-edd).

<Info>
  Subscription-based — contact Customer Success to enable the Checkout EDD service. Unsubscribed accounts receive a validation error (`Organization … is not configured for EDD service.`).
</Info>

## How it fits together

Prediction and fulfillment are separate systems — many consumer journeys request predictions without ever becoming a shipment, and checkout events are not visible in the Portal. The link is made by you:

<Steps>
  <Step title="Request a prediction at checkout">
    ```bash theme={null}
    curl --request POST \
      --url https://api.perform.ai/v1/edd/checkout/ \
      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{
        "to_address": { "city": "Singapore", "postal_code": "049145", "country_code": "SG" },
        "from_address": { "city": "Berlin", "postal_code": "10115", "country_code": "DE" },
        "carrier_reference": ["dhl-ecommerce-de"],
        "shipping_service": ["standard"]
      }'
    ```

    The **minimum** input is `from_address` and `to_address`, each with `country` or `country_code` — but prediction quality scales with input: postal codes and cities, a `carrier_reference` (your default or most common carrier), the `shipping_service`, and — for marketplaces — the `merchant_id`, since fulfillment speed varies by merchant.
  </Step>

  <Step title="Show the estimate">
    The response carries **one entry per requested carrier**, each with its own `checkout_id`:

    ```json theme={null}
    {
      "api_response": 200,
      "request_id": "6f1c2c9e-3d1a-4d2e-9d6b-0f1f7e3a5c21",
      "data": [
        {
          "carrier_reference": "dhl-ecommerce-de",
          "checkout_id": "b9f5b625-d08b-460d-b3a3-2d3e83fc0f00",
          "checkout_edd": {
            "start": "2026-09-25T02:30:00Z",
            "end": "2026-09-26T02:30:00Z",
            "type": "datetime_range",
            "start_timezone": "UTC",
            "end_timezone": "UTC"
          }
        }
      ]
    }
    ```

    Timestamps are UTC — convert to the shopper's timezone before displaying (most integrations show the date part only). `type` is `datetime_range` when `end` is later than `start`, otherwise `datetime_single`. Requesting several carriers in one call lets you compare EDDs and show the best option.
  </Step>

  <Step title="Link the prediction when the order confirms">
    Store the `checkout_id` of the carrier the consumer actually selected, and when you [create the Shipment](/guides/create-shipment), send it back in `additional_info` — optionally with `checkout_time`, the moment checkout completed:

    ```json theme={null}
    {
      "shipment_id": "SHP-2026-000377",
      "carrier_reference": "dhl-ecommerce-de",
      "additional_info": {
        "checkout_id": "b9f5b625-d08b-460d-b3a3-2d3e83fc0f00",
        "checkout_time": "2026-09-22T02:35:10Z"
      }
    }
    ```

    Linking works **at Shipment creation only** — Update Shipment ignores `checkout_id`. Each checkout event links to one Shipment and vice versa, permanently. Once linked, the checkout EDD appears in the Shipment's Parcel Details and is measured against the actual delivery.
  </Step>
</Steps>

## Rules that trip integrators up

* **`carrier_reference` and `shipping_service` are lists**, even for a single value: `["dhl-ecommerce-de"]` — and only one of the two may contain multiple values per request. Every carrier reference must be configured in **Settings > Carriers**; an empty list is rejected.
* **Checkout inputs don't carry over.** Neither the `carrier_reference` nor the `line_items` you send here transfer to the Shipment — provide them again at Create Shipment. Line items also aren't auto-calculated: send the weights and totals you want the model to see (each line item requires `product_name`; weights require their unit fields; cost fields require `currency_code`).
* **`shipment_value` is strict:** `<number> <CURRENCY>` with a valid ISO 4217 code (`135.50 SGD`) — no space or extra characters means rejection.
* **Simulate order times** with `order_target_time` + `order_target_timezone` (IANA ID) — the EDD calculation starts there instead of "now", and your account's warehouse cut-off and processing rules apply from that moment.
* **Custom model inputs** go in `prediction_payload` — fields are agreed during your POC. Three keys are also read by the platform (`handling_instructions`, `warehouse_ref`, `carrier_service`); a key must not appear both inside `prediction_payload` and at the top level.
* **Validation is all-or-nothing** — any invalid part means no checkout event and no `checkout_id`.
* **This service's envelope differs from the v5 API:** `api_response` is a number, errors arrive in a `data` array, and every response carries a `request_id` — quote it when contacting support.