> 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/resources/tutorials/standard-order-confirmation.md).
# Standard Order Confirmation
This tutorial builds a complete, valid Order Confirmation request for a single-item standard order.
**Base URL:** `https://checkout-api-gocas.sandbox.eshopworld.com`
**Endpoint:** `POST /api/v3/Retailer/Confirmation`
***
### The Scenario
| Detail | Value |
| ----------------- | -------------------------- |
| Product | Classic Leather Wallet × 1 |
| SKU | `SKU-00123` |
| HS code | `4202.32` |
| Retailer currency | EUR |
| Shopper currency | USD |
| Unit retail price | €89.95 / $97.79 |
| FX rate | \~1.0872 EUR→USD |
| Duty (12.5%) | €11.24 / $12.22 |
| Delivery | €8.00 / $8.70 |
| Administration | €2.50 / $2.72 |
| Grand total | €111.69 / $121.43 |
| Delivery country | United States (`US`) |
| Shopper language | English US (`en-US`) |
| Payment method | Visa credit card |
***
{% stepper %}
{% step %}
### Request Shell
Start with the required top-level fields. Every one of these must be present or the request is immediately rejected with `400`.
```json
{
"retailerCartId": "CART-2024-78542",
"eShopWorldOrderNumber": "ESW-20241101-00012345",
"deliveryCountryIso": "US",
"cartType": "Standard",
"checkoutTotal": { ... },
"paymentDetails": { ... },
"lineItems": [ ... ],
"charges": { ... },
"contactDetails": [ ... ]
}
```
| Required field | Description |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `retailerCartId` | Your internal cart or order reference. Max 100 characters. Used for reconciliation on your side. |
| `eShopWorldOrderNumber` | The ESW order identifier assigned during the checkout session. Max 36 characters. This is provided to you by ESW — do not generate it yourself. |
| `deliveryCountryIso` | ISO 3166-1 alpha-2 code for the shopper's delivery country. Exactly 2 characters. |
| `cartType` | `"Standard"` for a normal paid order. Use `"ZeroValue"` for complimentary/gifted orders. |
| `checkoutTotal` | The total amount the shopper was charged. Dual-currency `AmountRequestDto`. |
| `paymentDetails` | The primary payment method and pre-authorization details. |
| `lineItems` | The products in the cart. Minimum one item required. |
| `charges` | The order-level charge breakdown. Must include `total`. |
| `contactDetails` | Shopper delivery and/or payment address details. |
| {% endstep %} | |
{% step %}
### Add `checkoutTotal`
The checkout total is the single number that confirms what the shopper paid. It must match `charges.total` exactly.
```json
"checkoutTotal": {
"retailer": {
"currency": "EUR",
"amount": "111.69"
},
"shopper": {
"currency": "USD",
"amount": "121.43"
}
}
```
{% endstep %}
{% step %}
### Add `paymentDetails`
Payment details capture the method and timing of the pre-authorization. `method` and `time` are required.
```json
"paymentDetails": {
"method": "Visa",
"methodCardBrand": "Visa",
"time": "2024-11-01T14:23:00Z",
"fraudHold": false,
"amountPaid": 121.43
}
```
| Field | Required | Notes |
| ----------------- | -------- | --------------------------------------------------------------------------------- |
| `method` | ✅ | Payment method name as agreed with ESW, e.g. `"Visa"`, `"Mastercard"`, `"PayPal"` |
| `time` | ✅ | UTC ISO 8601 datetime of pre-authorization |
| `methodCardBrand` | ❌ | Card brand if applicable — often same as `method` for card payments |
| `fraudHold` | ❌ | `true` if the payment is being held for fraud review |
| `amountPaid` | ❌ | Numeric amount paid — note this is a `number` type, not a string |
| `isOverCounter` | ❌ | `true` for deferred payment methods (e.g. convenience store payment in Japan) |
| `ticketDetails` | ❌ | Payment voucher details for over-counter and ticket-based payment methods |
| {% endstep %} | | |
{% step %}
### Add `lineItems`
Each line item describes one distinct product in the cart. Three nested objects are required on every line item: `product`, `estimatedDeliveryDate`, and `charges`.
{% code expandable="true" %}
```json
"lineItems": [
{
"quantity": 1,
"lineItemId": 1,
"product": {
"productCode": "SKU-00123",
"hsCode": "4202.32",
"title": "Classic Leather Wallet",
"description": "Slim bifold wallet in full-grain leather",
"color": "Tan",
"size": "One Size",
"imageUrl": "https://cdn.mybrand.com/images/sku-00123.jpg",
"category": "ApparelAccessories",
"isReturnProhibited": false,
"productUnitPriceInfo": {
"price": {
"retailer": { "currency": "EUR", "amount": "89.95" },
"shopper": { "currency": "USD", "amount": "97.79" }
}
}
},
"estimatedDeliveryDate": {
"fromEShopWorldRangeFrom": "2024-11-07T00:00:00Z",
"fromEShopWorldRangeTo": "2024-11-11T00:00:00Z"
},
"charges": {
"subTotal": {
"retailer": { "currency": "EUR", "amount": "101.19" },
"shopper": { "currency": "USD", "amount": "110.01" }
},
"subTotalBeforeTaxesAndCartDiscountsApplied": {
"retailer": { "currency": "EUR", "amount": "89.95" },
"shopper": { "currency": "USD", "amount": "97.79" }
},
"duty": {
"retailer": { "currency": "EUR", "amount": "11.24" },
"shopper": { "currency": "USD", "amount": "12.22" }
}
}
}
]
```
{% endcode %}
product field reference
| Field | Required | Constraint | Description |
| ---------------------- | -------- | -------------------- | ------------------------------------------------------------------------ |
| `productCode` | ✅ | Max 100 chars | Your SKU or unique product identifier |
| `hsCode` | ✅ | Max 12 chars | Harmonised System code |
| `title` | ✅ | Max 100 chars | Localised product title shown to shopper |
| `description` | ✅ | No limit | Localised product description |
| `imageUrl` | ❌ | ≤ 20KB, retina-ready | Thumbnail image URL |
| `color` | ❌ | Max 100 chars | Item colour |
| `size` | ❌ | Max 100 chars | Item size |
| `category` | ❌ | — | ESW product category — should match the category used in the Catalog API |
| `isReturnProhibited` | ❌ | boolean | `true` if the item cannot be returned under the standard policy |
| `productUnitPriceInfo` | ❌ | — | Per-unit price including any item-level discounts |
#### `estimatedDeliveryDate` field reference
| Field | Description |
| ------------------------- | ------------------------------------------------------- |
| `fromRetailer` | Single estimated delivery date provided by the retailer |
| `fromEShopWorld` | Single estimated delivery date provided by ESW |
| `fromEShopWorldRangeFrom` | Start of ESW's estimated delivery window |
| `fromEShopWorldRangeTo` | End of ESW's estimated delivery window |
All four fields are optional, but at least one should be provided.
{% endstep %}
{% step %}
### Add `charges`
The order-level charges must include `total`, which must equal `checkoutTotal`. Add the optional breakdown fields for any charges that apply.
{% code expandable="true" %}
```json
"charges": {
"total": {
"retailer": { "currency": "EUR", "amount": "111.69" },
"shopper": { "currency": "USD", "amount": "121.43" }
},
"totalBeforeTaxesAndCartDiscountsApplied": {
"retailer": { "currency": "EUR", "amount": "89.95" },
"shopper": { "currency": "USD", "amount": "97.79" }
},
"duty": {
"retailer": { "currency": "EUR", "amount": "11.24" },
"shopper": { "currency": "USD", "amount": "12.22" }
},
"delivery": {
"retailer": { "currency": "EUR", "amount": "8.00" },
"shopper": { "currency": "USD", "amount": "8.70" }
},
"administration": {
"retailer": { "currency": "EUR", "amount": "2.50" },
"shopper": { "currency": "USD", "amount": "2.72" }
}
}
```
{% endcode %}
**Reconciliation:**
```ruby
lineItems[0].charges.subTotal = €101.19 / $110.01
+ charges.delivery = €8.00 / $8.70
+ charges.administration = €2.50 / $2.72
─────────────────────
charges.total = €111.69 / $121.43 ✅ matches checkoutTotal
```
{% endstep %}
{% step %}
### Add `contactDetails`
Contact details provide the shopper's delivery address. The array must contain at least one entry. `contactDetailType` and `country` are required on each entry.
{% code expandable="true" %}
```json
"contactDetails": [
{
"contactDetailType": "IsDelivery",
"firstName": "Jane",
"lastName": "Smith",
"address1": "350 Fifth Avenue",
"address2": "Suite 1200",
"city": "New York",
"region": "NY",
"postalCode": "10118",
"country": "US",
"email": "jane.smith@example.com",
"telephone": "+12125551234",
"isSelected": true,
"isDefault": false,
"saveToProfile": false,
"status": "Added"
}
]
```
{% endcode %}
To include both a delivery and a payment address, add a second entry with `contactDetailType: "IsPayment"`.
{% endstep %}
{% step %}
### Add Optional Context (Recommended)
These optional objects are not required but are strongly recommended for a complete integration.
#### `shopperCheckoutExperience`
Captures the shopper's language preference and marketing consent. `shopperCultureLanguageIso` is the only required field inside this object.
```json
"shopperCheckoutExperience": {
"shopperCultureLanguageIso": "en-US",
"emailMarketingOptIn": true,
"smsMarketingOptIn": false,
"saveAddressForNextPurchase": false,
"registeredProfileId": "PROFILE-98765"
}
```
#### `deliveryOption`
Specifies the ESW delivery option code the shopper selected.
```json
"deliveryOption": {
"deliveryOption": "STD_US",
"isShipToStore": false,
"isMultiOrigin": false
}
```
#### `pricingSynchronizationId`
If your checkout session used a specific FX rate snapshot, pass its ID here to ensure ESW can reconcile the shopper amounts correctly.
```json
"pricingSynchronizationId": "psync-abc123def456"
```
{% endstep %}
{% step %}
### The Complete Request
Assembling all steps, here is the full valid request body:
{% code expandable="true" %}
```json
{
"retailerCartId": "CART-2024-78542",
"eShopWorldOrderNumber": "ESW-20241101-00012345",
"deliveryCountryIso": "US",
"cartType": "Standard",
"pricingSynchronizationId": "psync-abc123def456",
"checkoutTotal": {
"retailer": { "currency": "EUR", "amount": "111.69" },
"shopper": { "currency": "USD", "amount": "121.43" }
},
"paymentDetails": {
"method": "Visa",
"methodCardBrand": "Visa",
"time": "2024-11-01T14:23:00Z",
"fraudHold": false,
"amountPaid": 121.43
},
"charges": {
"total": {
"retailer": { "currency": "EUR", "amount": "111.69" },
"shopper": { "currency": "USD", "amount": "121.43" }
},
"totalBeforeTaxesAndCartDiscountsApplied": {
"retailer": { "currency": "EUR", "amount": "89.95" },
"shopper": { "currency": "USD", "amount": "97.79" }
},
"duty": {
"retailer": { "currency": "EUR", "amount": "11.24" },
"shopper": { "currency": "USD", "amount": "12.22" }
},
"delivery": {
"retailer": { "currency": "EUR", "amount": "8.00" },
"shopper": { "currency": "USD", "amount": "8.70" }
},
"administration": {
"retailer": { "currency": "EUR", "amount": "2.50" },
"shopper": { "currency": "USD", "amount": "2.72" }
}
},
"lineItems": [
{
"quantity": 1,
"lineItemId": 1,
"product": {
"productCode": "SKU-00123",
"hsCode": "4202.32",
"title": "Classic Leather Wallet",
"description": "Slim bifold wallet in full-grain leather",
"color": "Tan",
"size": "One Size",
"imageUrl": "https://cdn.mybrand.com/images/sku-00123.jpg",
"category": "ApparelAccessories",
"isReturnProhibited": false,
"productUnitPriceInfo": {
"price": {
"retailer": { "currency": "EUR", "amount": "89.95" },
"shopper": { "currency": "USD", "amount": "97.79" }
}
}
},
"estimatedDeliveryDate": {
"fromEShopWorldRangeFrom": "2024-11-07T00:00:00Z",
"fromEShopWorldRangeTo": "2024-11-11T00:00:00Z"
},
"charges": {
"subTotal": {
"retailer": { "currency": "EUR", "amount": "101.19" },
"shopper": { "currency": "USD", "amount": "110.01" }
},
"subTotalBeforeTaxesAndCartDiscountsApplied": {
"retailer": { "currency": "EUR", "amount": "89.95" },
"shopper": { "currency": "USD", "amount": "97.79" }
},
"duty": {
"retailer": { "currency": "EUR", "amount": "11.24" },
"shopper": { "currency": "USD", "amount": "12.22" }
}
}
}
],
"contactDetails": [
{
"contactDetailType": "IsDelivery",
"firstName": "Jane",
"lastName": "Smith",
"address1": "350 Fifth Avenue",
"address2": "Suite 1200",
"city": "New York",
"region": "NY",
"postalCode": "10118",
"country": "US",
"email": "jane.smith@example.com",
"telephone": "+12125551234",
"isSelected": true,
"isDefault": false,
"saveToProfile": false,
"status": "Added"
}
],
"shopperCheckoutExperience": {
"shopperCultureLanguageIso": "en-US",
"emailMarketingOptIn": true,
"smsMarketingOptIn": false,
"saveAddressForNextPurchase": false,
"registeredProfileId": "PROFILE-98765"
},
"deliveryOption": {
"deliveryOption": "STD_US",
"isShipToStore": false,
"isMultiOrigin": false
}
}
```
{% endcode %}
{% endstep %}
{% step %}
### Sending the Request
```http
POST /api/v3/Retailer/Confirmation
Host: checkout-api-gocas.sandbox.eshopworld.com
Authorization: Bearer
Content-Type: application/json
{ ...request body above... }
```
#### Success response — `200 OK`
```json
{
"orderNumber": "RET-2024-78542",
"errors": []
}
```
| Field | Description |
| ------------- | ---------------------------------------------------------- |
| `orderNumber` | The retailer-side order number generated and stored by ESW |
| `errors` | Empty array on success |
Store `orderNumber` — it is your confirmed order reference on the ESW side and should be linked to your internal `retailerCartId`.
#### Error response — example `400 Bad Request`
```json
{
"orderNumber": null,
"errors": [
{
"code": 1001,
"message": "checkoutTotal is required"
}
]
}
```
{% endstep %}
{% endstepper %}
***
### Pre-Submission Checklist
Before calling the endpoint, verify:
* [ ] `retailerCartId` is unique and matches your internal cart reference
* [ ] `eShopWorldOrderNumber` was provided by ESW during the checkout session — not self-generated
* [ ] `deliveryCountryIso` is exactly 2 characters, uppercase ISO 3166-1 alpha-2
* [ ] `cartType` is `"Standard"` or `"ZeroValue"` — no other values are accepted
* [ ] `checkoutTotal` matches `charges.total` — both `retailer` and `shopper` sides
* [ ] All `amount` fields are strings, not numbers
* [ ] All `currency` fields are exactly 3 uppercase characters
* [ ] Every `AmountRequestDto` has both `retailer` and `shopper` present
* [ ] Every line item has `product`, `estimatedDeliveryDate`, and `charges.subTotal`
* [ ] `product.productCode`, `product.hsCode`, `product.title`, and `product.description` are present on every product
* [ ] Every `contactDetails` entry has `contactDetailType` and `country`
* [ ] `paymentDetails.method` and `paymentDetails.time` are present
* [ ] Line item subtotals sum correctly to `charges.total` after adding order-level charges
---
# 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/resources/tutorials/standard-order-confirmation.md?ask=&goal=
```
`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.