> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/checkout-api/checkout-api/overview.md).

# Overview

The Checkout API, also known as the Preorder API, sends the cart information as well as the shopper and retailer configuration details to the ESW Checkout system.

{% hint style="info" icon="basket-shopping" %}
When a shopper clicks **Checkout** on the retailer site, the *preorder* payload is created and sent to ESW. It includes cart information and shopper and retailer configuration details.
{% endhint %}

When the Checkout API receives a valid request,

1. A unique redirect `URL` is returned in the response.
2. When the shopper opens this link, they are redirected to the Checkout UI where they can review the order details and enter shipping, billing, and payment details.
3. If the payment is successful, the order confirmation page is <kbd>displayed</kbd> to the shopper.

### **Features Of Preorder**

The following are some of the advanced features of the preorder:

* **Registered Shoppers:** Prepopulate the shipping and billing details of the registered shoppers on the checkout page.
* **Shipping Override:** This allows you to pass the shipping rate that needs to be charged to the shopper. This is applicable if you offer shipping promotions.
* **Order Discount:** Allows you to display the discount value to the shoppers throughout their journey. You can provide the discount value and it will be displayed to the shopper throughout the checkout process.
* **Promotional codes:** This allows you to display the promotional codes that have been applied to an order, including the amount of discount applied (in monetary or percentage terms) plus a brief description of the promotion.

### Key Fields <a href="#key-values" id="key-values"></a>

The following key fields are sent in the preorder

| Field                | Description                                |
| -------------------- | ------------------------------------------ |
| `retailerCartId`     | Unique identifier for the retailer cart.   |
| `deliveryCountryIso` | Two-letter ISO 3166 delivery country code. |
| `lineItems`          | Items included in the cart.                |

***

### **Order Confirmation** <a href="#order-confirmation" id="order-confirmation"></a>

The Order Confirmation process is implemented using ESW’s Order Confirmation webhook. Each time an order is completed, a payload containing the required parameters is sent from the webhook. ESW supports an `Asynchronous` and `Synchronous` flows of Order Confirmation request processing.

* In the **synchronous flow**, the shopper is redirected to the Order Confirmation page **only after** the order confirmation processing is fully complete at the backend. This means it might take longer for the shopper to see the Order Confirmation page because the system waits for all processing to finish before redirecting.
* In the **asynchronous flow**, the shopper is redirected to the Order Confirmation page **immediately** after a successful payment. However, the order confirmation processing continues in the background. This makes the process appear faster to the shopper, even though the backend is still working on the order confirmation.

{% hint style="info" %}
To learn more about this offering reach out to your ESW representative.

**Read More :** [Order Confirmation Webhook](/checkout-api/resources/order-confirmation-webhook.md)
{% endhint %}

{% tabs %}
{% tab title="Synchronous" %}
{% code expandable="true" %}

```mermaid
%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "Arial, sans-serif",
    "primaryColor": "#007A4E",
    "primaryTextColor": "#1E2221",
    "primaryBorderColor": "#007A4E",
    "lineColor": "#1E2221",
    "signalColor": "#1E2221",
    "signalTextColor": "#1E2221",
    "actorBkg": "#CFF3E4",
    "actorTextColor": "#1E2221",
    "labelBoxBkgColor": "#DEEBE5",
    "labelTextColor": "#1E2221",
    "noteBkgColor": "#DEEBE5",
    "noteTextColor": "#1E2221",
    "sequenceNumberColor": "#FFD138",
    "activationBorderColor": "#007A4E",
    "activationBkgColor": "#80E8BF"
  }
}}%%
sequenceDiagram
    autonumber
    participant S as Shopper
    participant R as Retailer
    participant E as ESW
    participant UI as ESW Checkout UI

    S->>R: Click Checkout
    R->>E: Send checkout payload
    E-->>R: Return redirect URL
    R->>UI: Redirect shopper to ESW
    S->>UI: Complete checkout and pay
    E->>R: Send order confirmation webhook
    R-->>E: Return approval and retailer order number
    E-->>S: Show confirmation page
```

{% endcode %}

1. The shopper clicks **Checkout** on the retailer site.
2. The retailer sends the checkout payload to ESW.
3. ESW returns a redirect URL.
4. The shopper completes checkout in the ESW UI.
5. ESW posts to the retailer's hosted webhook for approval.
6. The retailer submits the final order confirmation to ESW
7. The shopper sees the confirmation page after processing completes.
   {% endtab %}

{% tab title="Asynchronous" %}
{% code expandable="true" %}

```mermaid
%%{init: {
  "theme": "base",
  "themeVariables": {
    "fontFamily": "Arial, sans-serif",
    "primaryColor": "#007A4E",
    "primaryTextColor": "#1E2221",
    "primaryBorderColor": "#007A4E",
    "lineColor": "#1E2221",
    "signalColor": "#1E2221",
    "signalTextColor": "#1E2221",
    "actorBkg": "#CFF3E4",
    "actorTextColor": "#1E2221",
    "labelBoxBkgColor": "#DEEBE5",
    "labelTextColor": "#1E2221",
    "noteBkgColor": "#DEEBE5",
    "noteTextColor": "#1E2221",
    "sequenceNumberColor": "#FFD138",
    "activationBorderColor": "#007A4E",
    "activationBkgColor": "#80E8BF"
  }
}}%%
sequenceDiagram
    autonumber
    participant S as Shopper
    participant R as Retailer
    participant E as ESW
    participant UI as ESW Checkout UI

    S->>R: Click Checkout
    R->>E: Send checkout payload
    E-->>R: Return redirect URL
    R->>UI: Redirect shopper to ESW
    S->>UI: Complete checkout and pay
    E-->>S: Show confirmation page immediately
    E->>R: Send order confirmation webhook in background
    R-->>E: Return approval and retailer order number
```

{% endcode %}

1. The shopper clicks **Checkout** on the retailer site.
2. The retailer sends the checkout payload to ESW.
3. ESW returns a redirect URL.
4. The shopper completes checkout in the ESW UI.
5. ESW redirects the shopper before confirmation processing completes.
6. ESW sends the order confirmation webhook in the background.
7. The retailer returns approval and can send its own order number.
   {% endtab %}
   {% endtabs %}

In both flows, the retailer can send its own order number during order confirmation. If no order number is returned, ESW uses the `retailerCartId`.

{% hint style="info" %}
For the post-payment confirmation, refer to [Order Confirmation](/checkout-api/checkout-api/api-methods/order-confirmation.md)
{% endhint %}

{% tabs %}
{% tab title="What you send" %}
A typical checkout request includes:

* A unique cart reference
* Line items, quantities, and product identifiers
* Pricing and currency data
* Delivery country
* Shopper language and localization data
* Product display data such as title, image, color, and size
* Retailer checkout settings and optional metadata
  {% endtab %}

{% tab title="Common capabilities" %}
The Checkout API supports several common integration patterns:

* **Registered shoppers**: prefill saved shipping and billing details
* **Delivery overrides**: pass retailer-defined delivery pricing when needed
* **Discounts and promo codes**: show cart discounts and applied promotions throughout checkout
* **Checkout UI metadata**: surface extra product or shopper-facing content in the checkout experience.
  {% endtab %}
  {% endtabs %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://developer.esw.com/checkout-api/checkout-api/overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.