> 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/order-api/resources/tutorials/creating-an-order.md). # Creating an Order `POST /v2/{tenantCode}/Order` creates a new order in ESW's system. {% tabs fullWidth="false" %} {% tab title="Code Walkthrough" %} {% @code-walkthrough/code-walkthrough title="Create Order" language="json" filename="Sample Request" code="POST /v2/my-brand-001/Order Authorization: Bearer Content-Type: application/json { "brandOrderReference": "ORD-2024-78542", "transactionReference": "C857B3CD-5EB7-426D-8741-812E5ED214C0", "transactionDateTime": "2024-11-01T14:23:00.000Z", "actionedBy": "Retailer", "actionedByUser": "", "orderType": "Sales", "shopperCurrencyIso": "USD", "retailerCurrencyIso": "EUR", "deliveryCountryIso": "US", "shopperExperience": { "languageIso": "en-US", "culture": "en-US" }, "deliveryOption": { "deliveryType": "Standard", "serviceLevel": "Standard" }, "contactDetails": \[ { "contactDetailType": "IsDelivery", "address": { "firstName": "Jane", "lastName": "Smith", "address1": "350 Fifth Avenue", "address2": "Suite 1200", "city": "New York", "region": "NY", "postalCode": "10118", "countryIso": "US" }, "email": "", "phone": "+12125551234" } ], "lineItems": \[ { "lineItemId": "1", "quantity": 1, "estimatedDeliveryDateFromRetailer": "2024-11-07T00:00:00.000Z", "product": { "productCode": "SKU-00123", "title": "Classic Leather Wallet", "description": "Slim bifold wallet in full-grain cowhide leather", "customsDescription": "Leather wallet — full-grain cowhide", "hsCode": "4202.32", "countryOfOriginIso": "IT", "color": "Tan", "size": "One Size", "imageUrl": "", "isCustomized": false, "isReturnProhibited": false, "productUnitPriceInfo": { "price": { "currency": "EUR", "amount": "89.95" } } } } ], "payment": { "method": "Visa", "amount": { "currency": "USD", "amount": "97.79" } }, "weight": { "value": 0.15, "unit": "kg" } }" steps="\[ {"label":"HTTP request line","description":"POST /v2/my-brand-001/Order — the tenant slug my-brand-001 is part of the URL path, not the body. Use Authorization: Bearer \ and Content-Type: application/json on every request.","lines":"1-3","tip":"Rotate bearer tokens regularly and never log them alongside order data"}, {"label":"Order references","description":"brandOrderReference is your own order ID — used to correlate this request back to your system. transactionReference is a UUID you generate per request for idempotency. transactionDateTime is when the order was placed in ISO-8601 UTC.","lines":"6-8","tip":"Store transactionReference — resubmitting with the same UUID prevents duplicate orders if the request is retried"}, {"label":"Actioned by","description":"actionedBy: Retailer identifies the actor type placing the order. actionedByUser is the specific system or user account — use a service account email for automated flows.","lines":"9-10","tip":"Use a dedicated service account email rather than a personal one for audit trail clarity"}, {"label":"Order type and currencies","description":"orderType: Sales distinguishes this from returns or exchanges. shopperCurrencyIso is what the customer paid in (USD), retailerCurrencyIso is the brand's home currency (EUR). deliveryCountryIso determines which pricing and duty rules apply.","lines":"12-15","tip":"shopperCurrencyIso and retailerCurrencyIso drive which FX rates and multipliers are selected from the pricing config"}, {"label":"Shopper experience","description":"languageIso and culture control localisation of any communications or documents generated for this order — invoices, emails, and customs paperwork will use this locale.","lines":"17-20","tip":"Always pass culture even if it duplicates languageIso — some downstream systems use only one or the other"}, {"label":"Delivery option","description":"deliveryType and serviceLevel select the fulfilment tier. Both Standard here — use Express or Premium where your carrier contract supports it.","lines":"22-25","tip":"Confirm available serviceLevel values with your carrier integration before going live"}, {"label":"Contact details","description":"contactDetailType: IsDelivery flags this address block as the shipping destination. Supply address, email, and phone together — all three are typically required for carrier label generation and customs.","lines":"27-43","tip":"Validate postalCode format against countryIso before submitting — mismatches cause carrier rejections"}, {"label":"Line item identifiers","description":"lineItemId is your own sequence number within this order. quantity is the unit count. estimatedDeliveryDateFromRetailer is the fulfilment promise date you are committing to in ISO-8601 UTC.","lines":"47-49","tip":"lineItemId must be unique within the order — use a simple incrementing integer per line"}, {"label":"Product identifiers and customs fields","description":"productCode is your SKU. title and description are shopper-facing. customsDescription appears on customs declarations — keep it plain and accurate. hsCode is the Harmonised System tariff code used to calculate duty. countryOfOriginIso is where the product was manufactured.","lines":"51-56","tip":"An incorrect hsCode can cause customs delays or mis-applied duty rates — verify against official tariff schedules"}, {"label":"Product attributes and flags","description":"color, size, and imageUrl are fulfilment and returns metadata. isCustomized: false means standard returns rules apply. isReturnProhibited: false means the item can be returned — set to true for perishables or bespoke goods.","lines":"57-61","tip":"Set isReturnProhibited accurately — it affects the returns flow and customer communications"}, {"label":"Unit price","description":"productUnitPriceInfo.price is the retailer's source price — always in the retailer's home currency (EUR here). This is the amount the pricing engine applies FX rates and multipliers to in order to derive the shopper-facing price.","lines":"62-67","tip":"Pass the clean source price with zero embedded rates if you use adjustedValue multipliers — passing a pre-marked-up price will double-count costs"}, {"label":"Payment","description":"method: Visa is the payment instrument. amount.currency must match shopperCurrencyIso (USD). amount.amount is the total the shopper was charged — the pricing engine will reconcile this against the calculated order total.","lines":"72-78","tip":"Always submit the actual charged amount, not a recalculated one — discrepancies trigger reconciliation alerts"}, {"label":"Weight","description":"weight.value and weight.unit represent the total shipment weight. Used for carrier rate selection, label generation, and customs documentation.","lines":"80-83","tip":"Use kg consistently — mixing units across orders causes carrier billing errors"} ]" fullWidth="false" %} {% endtab %} {% endtabs %} *** {% stepper %} {% step %} ### When to Call This Endpoint Call `POST /Order` after: * The shopper has completed checkout * Payment has been pre-authorised or confirmed * You have received an `eShopWorldOrderNumber` from ESW's checkout flow (if applicable) Do not call this endpoint to update or modify an existing order — use the activity, line item, or replacement endpoints for post-creation changes. {% endstep %} {% step %} ### Request Structure The `OrderCreate` body has 12 required fields and 6 optional fields.
Required | Field | Type | Description | | ---------------------- | --------------------------- | ---------------------------------------------- | | `brandOrderReference` | string | Your internal order number | | `transactionReference` | UUID string | Unique transaction ID — see Tutorial 1 | | `transactionDateTime` | ISO 8601 UTC | When the order was created in your system | | `actionedBy` | enum | Who created the order — typically `"Retailer"` | | `orderType` | enum | The type of order | | `shopperCurrencyIso` | string (ISO 4217) | The currency the shopper paid in | | `retailerCurrencyIso` | string (ISO 4217) | The retailer's home currency | | `deliveryCountryIso` | string (ISO 3166-1 alpha-2) | The shopper's delivery country | | `shopperExperience` | object | Language and experience preferences | | `contactDetails` | array | Delivery and/or billing address | | `lineItems` | array | The products in the order | | `deliveryOption` | object | The delivery method selected by the shopper |
Optional | Field | Description | | --------------------------- | ------------------------------------------------------ | | `weight` | Total order weight | | `parentBrandOrderReference` | Parent order reference for replacement/exchange orders | | `externalOrderId` | Any external system identifier | | `actionedByUser` | Human identifier — see Tutorial 1 | | `retailerInvoice` | Retailer invoice number and date | | `payment` | Payment method and amount details | | `originDetails` | Origin type and warehouse details | | `metadataItems` | Key-value pairs agreed with ESW | | `channelType` | Sales channel identifier |
{% endstep %} {% step %} ### Required Top-Level Fields #### `brandOrderReference` Your order number — the primary key by which you will reference this order in all subsequent API calls. It must be unique within your tenant. ```json "brandOrderReference": "ORD-2024-78542" ``` * Minimum length: 1 character * No maximum specified — but keep it consistent with your internal format * Used as the `{brandOrderReference}` path parameter on every subsequent Order endpoint call #### Currency fields Both currency fields are required and must be valid ISO 4217 three-letter codes. ```json "shopperCurrencyIso": "USD", "retailerCurrencyIso": "EUR" ``` | Field | Description | | --------------------- | -------------------------------------------------- | | `shopperCurrencyIso` | The currency the shopper saw prices in and paid in | | `retailerCurrencyIso` | The retailer's home/settlement currency | When the shopper pays in the retailer's home currency, both fields will be the same code. #### `deliveryCountryIso` Two-letter ISO 3166-1 alpha-2 country code for the delivery destination. ```json "deliveryCountryIso": "US" ``` {% endstep %} {% step %} ### `orderType` `orderType` describes the nature of the order. It must be one of the following values: | Value | Description | | --------------- | ----------------------------------------------------- | | `"Sales"` | A standard retail sale order — the most common type | | `"Return"` | A return order — the shopper is sending goods back | | `"Replacement"` | A replacement order created to send alternative goods | | `"Exchange"` | An exchange order — return and replacement combined | For a standard new purchase, use `"Sales"`. Replacement and exchange orders are typically created by ESW's systems in response to a replacement request — you may encounter these types when reading order state but rarely need to create them directly. ```json "orderType": "Sales" ``` {% endstep %} {% step %} ### `shopperExperience` `shopperExperience` captures the shopper's language and locale preference. `languageIso` is the only required field. ```json "shopperExperience": { "languageIso": "en-US", "culture": "en-US" } ``` | Field | Required | Description | | ------------- | -------- | --------------------------------------------------------------------------------------------------------- | | `languageIso` | ✅ | BCP 47 language tag — language code + country code, hyphen-separated e.g. `"en-US"`, `"fr-FR"`, `"ja-JP"` | | `culture` | ❌ | Culture/locale string — typically the same as `languageIso` | | {% endstep %} | | | {% step %} ### `deliveryOption` `deliveryOption` identifies the shipping method the shopper selected. It uses `DeliveryOptionCreate` which has two required fields. ```json "deliveryOption": { "deliveryType": "Standard", "serviceLevel": "Standard" } ``` | Field | Required | Description | | --------------- | -------- | --------------------------------------------- | | `deliveryType` | ✅ | The type of delivery — `DeliveryTypeOms` enum | | `serviceLevel` | ✅ | The service level — `ServiceLevel` enum | | `metadataItems` | ❌ | Key-value pairs agreed with ESW | #### `DeliveryTypeOms` values | Value | Description | | --------------- | ---------------------------------------------- | | `"Standard"` | Standard home delivery | | `"Express"` | Express home delivery | | `"ShipToStore"` | Click-and-collect — delivery to a retail store | #### `ServiceLevel` values | Value | Description | | ------------- | -------------------------- | | `"Standard"` | Standard service | | `"Express"` | Express service | | `"NextDay"` | Next business day delivery | | `"SameDay"` | Same-day delivery | | {% endstep %} | | {% step %} ### `contactDetails` `contactDetails` is an array of `ContactDetail` objects representing the shopper's delivery and/or billing addresses. At least one entry is required. {% code expandable="true" %} ```json "contactDetails": [ { "contactDetailType": "IsDelivery", "address": { "firstName": "Jane", "lastName": "Smith", "address1": "350 Fifth Avenue", "city": "New York", "region": "NY", "postalCode": "10118", "countryIso": "US" }, "email": "jane.smith@example.com", "phone": "+12125551234" } ] ``` {% endcode %} #### `ContactDetailsType` values | Value | Description | | -------------- | -------------------- | | `"IsDelivery"` | The shipping address | | `"IsPayment"` | The billing address | Multiple entries are applied first-to-last. Include both `IsDelivery` and `IsPayment` entries when the billing address differs from the delivery address.
OrderAddressDto fields | Field | Required | Max length | Description | | ------------ | -------- | ---------- | ----------------------------------- | | `countryIso` | ✅ | 2 chars | ISO 3166-1 alpha-2 delivery country | | `firstName` | ❌ | — | Recipient first name | | `lastName` | ❌ | — | Recipient last name | | `address1` | ❌ | — | Primary address line | | `address2` | ❌ | — | Secondary address line | | `address3` | ❌ | — | Tertiary address line | | `city` | ❌ | — | City | | `region` | ❌ | — | State or province | | `postalCode` | ❌ | — | Postal or ZIP code |
{% endstep %} {% step %} ### Line Items `lineItems` is an array of `OrderItemToCreate` objects. A minimum of one is required. ```json "lineItems": [ { "lineItemId": "1", "quantity": 1, "product": { ... }, "estimatedDeliveryDateFromRetailer": "2024-11-07T00:00:00.000Z", "metadataItems": [] } ] ```
OrderItemToCreate fields | Field | Required | Type | Description | | ----------------------------------- | -------- | --------------- | ------------------------------------------------------------------------------------------------------- | | `lineItemId` | ✅ | string | Unique identifier for this line within the order — typically `"1"`, `"2"`, `"3"` etc. Minimum length 1. | | `quantity` | ✅ | integer | Number of units of this product | | `product` | ✅ | `ProductCreate` | Product details — see Step 9 | | `estimatedDeliveryDateFromRetailer` | ❌ | ISO 8601 UTC | Retailer's estimated delivery date for this line item | | `metadataItems` | ❌ | array | Key-value pairs agreed with ESW |
#### `lineItemId` rules * Must be unique within the order — no two line items can share the same `lineItemId` * It is a string, not an integer — `"1"` not `1` * Used to target specific line items in subsequent LineItemActivity, LineItemAppeasement, and LineItem operations * Keep it stable — the same `lineItemId` is used throughout the order lifecycle to identify this line {% endstep %} {% step %} ### Product (`ProductCreate`) Each line item contains one `ProductCreate` object describing the product. {% code expandable="true" %} ```json "product": { "productCode": "SKU-00123", "title": "Classic Leather Wallet", "description": "Slim bifold wallet in full-grain cowhide leather", "customsDescription": "Leather wallet — full-grain cowhide", "hsCode": "4202.32", "countryOfOriginIso": "IT", "imageUrl": "https://cdn.mybrand.com/images/sku-00123.jpg", "color": "Tan", "size": "One Size", "isCustomized": false, "isReturnProhibited": false, "productUnitPriceInfo": { ... } } ``` {% endcode %}
ProductCreate field reference | Field | Required | Description | | ---------------------- | -------- | ----------------------------------------------------------------------------------------- | | `productCode` | ✅ | Your SKU or unique product identifier. Min length 1. | | `title` | ✅ | Localised product title. Min length 1. | | `description` | ✅ | Localised product description. Min length 1. | | `productUnitPriceInfo` | ✅ | The unit price — see Step 10 | | `customsDescription` | ❌ | Description specifically for customs documentation — if omitted ESW may use `description` | | `hsCode` | ❌ | Harmonised System code for customs classification | | `countryOfOriginIso` | ❌ | ISO 3166-1 alpha-2 country of manufacture | | `imageUrl` | ❌ | Thumbnail URL — max 20KB, must be retina-ready | | `color` | ❌ | Product colour | | `size` | ❌ | Product size | | `isCustomized` | ❌ | `true` if the item is a bespoke or personalised product | | `isReturnProhibited` | ❌ | `true` if the item cannot be returned under the standard returns policy | | `wholesalePriceInfo` | ❌ | Wholesale price — same structure as `productUnitPriceInfo` | | `weightInfo` | ❌ | Item weight — `value` (number) and `unit` (enum) |
{% endstep %} {% step %} ### `productUnitPriceInfo` `productUnitPriceInfo` is a `PriceInfo` object containing a single `price` field of type `Money`. ```json "productUnitPriceInfo": { "price": { "currency": "EUR", "amount": "89.95" } } ``` #### `Money` fields | Field | Type | Description | | ---------- | ------ | ------------------------------------------------------------------------------------------------ | | `currency` | string | ISO 4217 three-letter currency code — must be uppercase | | `amount` | string | The monetary amount as a string — period as decimal separator, no symbols or thousand separators | #### Which currency to use in `price` Use the **retailer's currency** (`retailerCurrencyIso`) for product prices. ESW uses the order-level `shopperCurrencyIso` and `retailerCurrencyIso` fields, combined with current FX rates, to derive the shopper-currency equivalents internally. You do not need to provide dual-currency amounts at the product level in this API. ```json "price": { "currency": "EUR", "amount": "89.95" } ```
amount format rules | Format | Valid | Notes | | ------------ | ----- | --------------------------------- | | `"89.95"` | ✅ | Standard two-decimal retail price | | `"14650"` | ✅ | Zero-decimal currency (JPY) | | `"0.00"` | ✅ | Zero price — valid | | `89.95` | ❌ | Number type — must be string | | `"$89.95"` | ❌ | Symbol included | | `"1,234.00"` | ❌ | Thousand separator included |
{% endstep %} {% step %} ### Optional Fields #### `payment` Captures payment method and amount. Useful for financial reconciliation. ```json "payment": { "method": "Visa", "amount": { "currency": "USD", "amount": "97.79" } } ``` #### `retailerInvoice` Retailer-side invoice reference for accounting and VAT purposes. ```json "retailerInvoice": { "invoiceNumber": "INV-2024-78542", "invoiceDate": "2024-11-01" } ``` #### `originDetails` The origin or warehouse from which the order ships. ```json "originDetails": { "originType": "Warehouse", "originCode": "WH-IT-MILAN" } ``` `OriginType` values: `"Warehouse"`, `"Store"`, `"Vendor"`. #### `weight` Total order weight — `value` (number) and `unit` (enum: `"kg"`, `"g"`, `"lb"`, `"oz"`). ```json "weight": { "value": 0.5, "unit": "kg" } ``` #### `metadataItems` Key-value pairs for additional context agreed with ESW. Use of these must be agreed in advance. ```json "metadataItems": [ { "name": "orderSource", "value": "MobileApp" }, { "name": "appVersion", "value": "4.2.1" } ] ``` {% endstep %} {% step %} ### `202 Accepted` Response On success the endpoint returns `202 Accepted`: ```json { "transactionReference": "C857B3CD-5EB7-426D-8741-812E5ED214C0" } ``` Store this `transactionReference` — it is the canonical identifier for the order creation transaction. Use `GET /Order/{brandOrderReference}` to confirm the order was successfully created and read back its initial state. {% endstep %} {% step %} ### Example A single-item Sales order — EUR-brand retailer, USD-paying shopper, delivery to the US. {% code lineNumbers="true" %} ```json POST /v2/my-brand-001/Order Authorization: Bearer Content-Type: application/json { "brandOrderReference": "ORD-2024-78542", "transactionReference": "C857B3CD-5EB7-426D-8741-812E5ED214C0", "transactionDateTime": "2024-11-01T14:23:00.000Z", "actionedBy": "Retailer", "actionedByUser": "system@mybrand.com", "orderType": "Sales", "shopperCurrencyIso": "USD", "retailerCurrencyIso": "EUR", "deliveryCountryIso": "US", "shopperExperience": { "languageIso": "en-US", "culture": "en-US" }, "deliveryOption": { "deliveryType": "Standard", "serviceLevel": "Standard" }, "contactDetails": [ { "contactDetailType": "IsDelivery", "address": { "firstName": "Jane", "lastName": "Smith", "address1": "350 Fifth Avenue", "address2": "Suite 1200", "city": "New York", "region": "NY", "postalCode": "10118", "countryIso": "US" }, "email": "jane.smith@example.com", "phone": "+12125551234" } ], "lineItems": [ { "lineItemId": "1", "quantity": 1, "estimatedDeliveryDateFromRetailer": "2024-11-07T00:00:00.000Z", "product": { "productCode": "SKU-00123", "title": "Classic Leather Wallet", "description": "Slim bifold wallet in full-grain cowhide leather", "customsDescription": "Leather wallet — full-grain cowhide", "hsCode": "4202.32", "countryOfOriginIso": "IT", "color": "Tan", "size": "One Size", "imageUrl": "https://cdn.mybrand.com/images/sku-00123.jpg", "isCustomized": false, "isReturnProhibited": false, "productUnitPriceInfo": { "price": { "currency": "EUR", "amount": "89.95" } } } } ], "payment": { "method": "Visa", "amount": { "currency": "USD", "amount": "97.79" } }, "weight": { "value": 0.15, "unit": "kg" } } ``` {% endcode %} {% code title="Response" %} ```json HTTP/1.1 202 Accepted { "transactionReference": "C857B3CD-5EB7-426D-8741-812E5ED214C0" } ``` {% endcode %} {% endstep %} {% step %} ### Common Errors | Error | Cause | Fix | | --------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------- | | `400` — `brandOrderReference` is required | Field missing or empty string | Ensure `brandOrderReference` is present with at least 1 character | | `400` — `transactionReference` must be a valid UUID | Malformed UUID | Use a standard UUID v4 generator — see Tutorial 1 | | `400` — `lineItems` must contain at least one item | Empty `lineItems` array | Provide at least one line item | | `400` — `productCode` is required | Product missing `productCode` | Every product must have a non-empty `productCode` | | `400` — `shopperCurrencyIso` must be 3 characters | Invalid ISO 4217 code | Use uppercase 3-letter code: `"USD"` not `"US"` | | `400` — `deliveryCountryIso` must be 2 characters | Invalid ISO 3166-1 code | Use uppercase 2-letter code: `"US"` not `"USA"` | | `400` — `amount` is not valid | `amount` sent as a number | Wrap in quotes: `"89.95"` not `89.95` | | `403` | JWT not scoped to this `tenantCode` | Verify token is issued for the correct tenant | | `404` | `tenantCode` not found | Confirm `tenantCode` matches your onboarding configuration | | {% endstep %} | | | | {% endstepper %} | | | --- # 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/order-api/resources/tutorials/creating-an-order.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.