> ## 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 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. ## OpenAPI ````yaml specs/checkout-v1.yaml POST /v1/edd/checkout/ openapi: 3.1.0 info: title: Perform.AI Checkout API (v1) version: 1.0.0 description: |- Predict Estimated Delivery Dates (EDD) at checkout. Create a checkout event and receive an EDD from your tailored machine-learning model or a generic model configured for your fulfillment timelines — one EDD entry per requested carrier. Subscription-based — contact Customer Success to enable the service; unconfigured accounts receive a validation error. Authentication uses the same Bearer token as the Public API v5. servers: - url: https://api.perform.ai security: - BearerAuth: [] tags: - name: Checkout description: Checkout-time delivery date prediction. paths: /v1/edd/checkout/: post: tags: - Checkout summary: Predict Checkout EDD description: |- 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. operationId: post-v1-edd-checkout requestBody: required: true content: application/json: schema: type: object required: - from_address - to_address properties: from_address: $ref: '#/components/schemas/CheckoutAddress' to_address: $ref: '#/components/schemas/CheckoutAddress' carrier_reference: type: array items: type: string minLength: 1 maxLength: 50 minItems: 1 maxItems: 50 description: >- 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. shipping_service: type: array items: type: string maxLength: 50 description: >- The 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. merchant_id: type: string maxLength: 50 description: >- Identifier of the merchant/supplier on your platform. Strongly recommended for marketplaces — fulfillment speed varies by merchant. order_target_time: type: string description: >- The 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`. order_target_timezone: type: string maxLength: 50 description: >- IANA timezone of `order_target_time`. Defaults to `UTC`; invalid IDs are rejected. order_source_type: type: string maxLength: 100 order_source_name: type: string maxLength: 100 shipment_value: type: string maxLength: 50 description: >- Total value of the items as ` ` with a valid ISO 4217 code, e.g. `35.50 SGD`. Values without the space, or with extra characters, are rejected. item_count: type: integer expected_delivery_from: type: string description: >- Start 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. expected_delivery_to: type: string description: Requires `expected_delivery_from`. ISO 8601. line_items: type: array items: $ref: '#/components/schemas/CheckoutLineItem' description: >- Items at the checkout stage. NOT carried over to a created Shipment. prediction_payload: type: object description: >- 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. example: 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 responses: '200': description: >- Prediction generated — one `data` entry per requested carrier reference, each with its own `checkout_id`. content: application/json: schema: type: object properties: api_response: type: integer description: >- `200` on success. Note: this service returns `api_response` as a number. request_id: type: - string - 'null' description: >- Correlation ID (echoed from an `X-Request-Id` request header when present). Quote it when contacting support. data: type: array items: type: object properties: carrier_reference: type: - string - 'null' description: >- The carrier reference this entry was calculated for; `null` when none was sent. checkout_id: type: string format: uuid description: >- This entry's checkout event identifier. Send the SELECTED carrier's `checkout_id` back in `additional_info.checkout_id` on Create Shipment. checkout_edd: type: object properties: start: type: string description: Start of the estimated window, UTC (`…Z`). end: type: string description: >- End of the window, UTC. Equal to `start` for a single-date EDD. start_timezone: type: string description: Currently always `UTC`. end_timezone: type: string description: Currently always `UTC`. type: type: string enum: - datetime_range - datetime_single description: >- `datetime_range` when `end` is later than `start`, otherwise `datetime_single`. Convert to the shopper's timezone before displaying; most integrations show the date part only. example: 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 '400': description: |- Validation failed — the body failed validation, a `carrier_reference` is not configured in your account, or the account is not configured for the EDD service. All-or-nothing: no checkout event is created. `error` carries field-level details (an object) or message strings (an array). content: application/json: schema: $ref: '#/components/schemas/CheckoutError' examples: field-validation: summary: Missing required field value: api_response: 4030 request_id: 6f1c2c9e-3d1a-4d2e-9d6b-0f1f7e3a5c21 data: - carrier_reference: - dhl-ecommerce-de msg: validation_error error: to_address: - This field is required. unconfigured-carrier: summary: Carrier reference not configured value: api_response: 4030 request_id: 6f1c2c9e-3d1a-4d2e-9d6b-0f1f7e3a5c21 data: - carrier_reference: - unknowncarrier msg: validation_error error: - >- carrier_reference unknowncarrier specified in request has not been created. '403': description: Authentication failed. content: application/json: schema: type: object properties: api_response: type: integer message: type: string example: api_response: 403 message: Key not authorized '429': description: Rate limit exceeded. '500': description: |- Server-side outcomes, each named in `msg`: `not_found_scope_configuration` — the account is configured but no model or decoding rule matches this request (unsupported corridor, unknown handling instruction); `service_unavailable` — the prediction or configuration service did not respond, retry with backoff; `internal_server_error` — unexpected error, quote `request_id` to support. content: application/json: schema: $ref: '#/components/schemas/CheckoutError' example: api_response: 500 request_id: 6f1c2c9e-3d1a-4d2e-9d6b-0f1f7e3a5c21 data: - msg: not_found_scope_configuration error: >- No matched EDD scope configuration for org_id: 1234, scope_type: edd_model components: schemas: CheckoutAddress: type: object description: >- 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. properties: country_code: type: string minLength: 2 maxLength: 2 description: >- ISO 3166-1 alpha-2 — preferred. When both are sent, `country_code` wins. country: type: string maxLength: 75 description: >- Country name — must match the ISO 3166-1 English short name exactly (`United States`, `Czechia`, `Viet Nam`); variants like `United States of America` or `Vietnam` are rejected. Prefer `country_code`. postal_code: type: string maxLength: 25 description: Strongly recommended — the biggest accuracy gain over country alone. city: type: string maxLength: 75 description: Strongly recommended. state_or_province: type: string maxLength: 75 region: type: string maxLength: 75 line1: type: string maxLength: 150 line2: type: string maxLength: 150 line3: type: string maxLength: 150 address_name: type: string maxLength: 50 location_type: type: string maxLength: 50 entity_reference: type: string maxLength: 50 salutation: type: string maxLength: 50 first_name: type: string maxLength: 150 last_name: type: string maxLength: 150 email: type: string format: email maxLength: 100 description: Not used for notifications. phone: type: string maxLength: 50 description: >- Not used for notifications. Stored as sent (no normalization); recommended format `+{country code}{number}`. company: type: string maxLength: 150 tax_id: type: string maxLength: 100 CheckoutLineItem: type: object required: - product_name description: >- One product at the checkout stage. The checkout service does not derive missing weights or totals — send the values you want the model to see. properties: product_name: type: string maxLength: 100 description: Customer-facing product name. Required in each line item. product_id: type: string maxLength: 50 product_reference: type: string maxLength: 50 product_category: type: string maxLength: 100 product_description: type: string maxLength: 500 product_origin_country_code: type: string minLength: 2 maxLength: 2 hs_code: type: string maxLength: 20 customs_description: type: string maxLength: 500 quantity: type: integer product_url: type: string format: uri product_weight: type: number description: Weight of one unit. Requires `product_weight_unit`. product_weight_unit: type: string maxLength: 5 description: Required when `product_weight` is sent. line_item_weight: type: number description: Total weight of this line. Requires `line_item_weight_unit`. line_item_weight_unit: type: string maxLength: 5 description: Required when `line_item_weight` is sent. currency_code: type: string minLength: 3 maxLength: 3 description: >- ISO 4217. Required when any cost field is sent; use the same currency across all line items. product_cost: type: number subtotal_cost: type: number discount_amount: type: number tax_amount: type: number misc_cost: type: number total_price: type: number CheckoutError: type: object description: >- This service's error envelope differs from the Public API v5: `api_response` is a number, a `request_id` is included, and errors arrive as a `data` array. properties: api_response: type: integer request_id: type: - string - 'null' data: type: array items: type: object properties: carrier_reference: type: - array - 'null' items: type: string msg: type: string description: >- `validation_error`, `not_found_scope_configuration`, `service_unavailable`, or `internal_server_error`. error: description: >- Field-level details (object of field → messages) or an array of message strings. securitySchemes: BearerAuth: type: http scheme: bearer description: >- The same Bearer token as the Public API v5 — generate it with `POST /auth/oauth/token/`. ````