# ESW Developer Platform ESW developer documentation for APIs, integrations, authentication, checkout, orders, webhooks, setup guides, and technical references.

ESW Developer Documentation Portal

Explore our developer documentation for eCommerce integrations, REST APIs, authentication, checkout, webhooks, setup guides, and more.

{% columns %} {% column width="25%" %}

			Cover image
Configure your developer environment and launch faster.			/files/2IsHQnugVFiS1QfQUMOA	/spaces/S1VBiRsVGuY2lQIOaVbI/pages/PbYb0GukRhiS4qCHdRal

{% endcolumn %} {% column width="25%" %}

			Cover image
Explore our integration options to find what best fits your business.		https://esw.com/	/files/IC9zVaZsnSBTC6Pw36Iu	/spaces/bB3UcHnWX3RLHHoolsLd

{% endcolumn %} {% column %}

			Cover image
Browse our API documentation for technical reference details	API References	https://esw.com/	/files/lr08tWEMQW1rFYx0d2Pj	/spaces/sF5ifQjsfzalpf6LcO1G/pages/Xh8kfHbBIugc76WYNqOX

{% endcolumn %} {% column %}

			Cover image
Discover the ESW Agentic Commerce Hub for faster task management.	Agentic Commerce Hub		/files/zG5aO0O3peKQY1cd2kI0	/spaces/oNiYzXq5W9lF4B0fAZ9e/pages/JIgaZMvLkPNFqXMIZfW8

{% endcolumn %} {% endcolumns %} {% columns %} {% column width="41.66666666666667%" valign="middle" %}

Get Started with APIs

ESW offers REST APIs and integration patterns in its Developer Portal, using resource-based URLs, JSON payloads, and standard HTTP status codes.

Go to Authentication

{% endcolumn %} {% column width="58.33333333333333%" valign="middle" %} ```json POST /api/v4/Package HTTP/1.1 Host: logistics-package-api.sandbox.eshopworld.com/ Authorization: Bearer YOUR_SECRET_TOKEN { "brandCode": "GOC", "orderReference": "ABC1234567890", "packageReference": "AAA1234567890", "orderType": "CHECKOUT", "weight": { "weight": 1.34, "weightUnit": "KG" }, ``` {% endcolumn %} {% endcolumns %}

ESW Help Center and Client Hub

	Cover image
Client Hub Use the ESW Client Hub to manage platform configuration, pricing, messaging, roles, and self-service support.	/files/tKhwls7zNO5uTm7zOcHt	https://esp.eshopworld.com/
Help Center Access ESW user guides, onboarding resources, and support documentation to get started faster.	/files/jL86O2bsflB4dqaDGrMw	https://help.esw.com

Cover image

Client Hub

Use the ESW Client Hub to manage platform configuration, pricing, messaging, roles, and self-service support.

/files/tKhwls7zNO5uTm7zOcHt

https://esp.eshopworld.com/

Help Center

Access ESW user guides, onboarding resources, and support documentation to get started faster.

/files/jL86O2bsflB4dqaDGrMw

https://help.esw.com

		Cover image
Customs Catalog API	/spaces/JWssSKqn34oo0GTi1dVW/pages/0ljInR3wX9yfMZEvlhBK	/files/K10bRZXzkcV3PjAGhE6H
Pricing Advisor API	/spaces/nTL8tl9tUOtaGkSQHGiK/pages/EIGFjqZfvd6s3Op32yBs	/files/b8LC2MG2mbq25HKBV784
Checkout API	/spaces/chjZv79baUiFWxjmZavx/pages/sB155FV2pgYHdCAgTy5O	/files/MvWO05Z1Gev4Ptg3NOop
Package API	/spaces/ZhcwGHfYyTPT5VkoQl32/pages/66UkEjgBkmrmojeKVv7P	/files/jRawzEG8aLyj4q3nkUOf
Order API	/spaces/9sJh9mebwGhWfzKvcTnt/pages/202esirNcOhTsSfTGXEV	/files/DZii9emz1RH0GX9nZYoe
Returns API	/spaces/a921jcoPME0jDOOuVtoT/pages/G2GxBBnsFApQzL2IXCko	/files/Q50HPbKyKDurbvzUFlnc
Fulfillment API	/spaces/OA1tnmF5u1Lk9QuR6ayG/pages/aLbDQUGvqk3mO0bRA0dc	/files/axIxS5dhujcjoyTcr3H2
Callback API	/spaces/Q1HVASS6ihhZefH3FyG1/pages/QbefZqpQGdJwhjGvqxhi	/files/wkRxwM9cHG5s8nvKio5O
API References	/spaces/sF5ifQjsfzalpf6LcO1G/pages/Xh8kfHbBIugc76WYNqOX	/files/niNr9oLhiaw2PxaMpysB

Finance and Settlement

Making worldwide commerce simple

Our finance solutions are designed to streamline cross-border transactions, ensuring seamless settlements and transparent billing processes for retailers and shoppers alike.

Settlement & Billing Pricing Order Flow Invoicing, Tax and Duties

***

		Cover image
Decrease complexity	ESW decreases complexity to provide a seamless experience to shoppers everywhere.	/files/lEafxCMfDJHZKOQygjmj
Shared revenue model	ESW has a shared revenue model and a vested interest in your growth and cross border potential.	/files/Mxl3Ne4ULu9ewc4bLAiH
Tax and compliance	ESW handles tax, compliance and collection of money from PSPs.	/files/yqlx31XKvvg2FHrpjrtU
Flexibility	Flexible settlement cadences to match your internal requirements: weekly, fortnightly, or monthly.	/files/CX6EBaXSsW84YzO8fvVv
Cashflow	There is no payout threshold in ESW. ESW will remit the full value of your settlement net of our fees in the agreed settlement period.	/files/OmqmQY29nK62GuqwISUm
Payment processing	ESW will remit payment within two business days of your selected settlement period, via bank transfer or ACH to your designated account	/files/eEX5wMwS5rVjeZyxiwHZ

***

What this means

ESW Benefits

{% tabs %} {% tab title="For you" %} {% @code-walkthrough/alert-block title="" message="Receive a single payment to your chosen bank account on your selected day, in line with our flexible payment terms." type="success" %} {% @code-walkthrough/alert-block title="" message="ESW deducts a checkout fee from this as agreed per the contract." type="success" %} {% @code-walkthrough/alert-block title="" message="ESW takes care of all relevant tax returns and compliance on your behalf." type="success" %} {% @code-walkthrough/alert-block title="" message="ESW deals directly with every payment provider we support." type="success" %} {% endtab %} {% tab title="For your team" %} {% @code-walkthrough/alert-block title="" message="Ease of reconciliation. " type="success" %} {% @code-walkthrough/alert-block title="" message="A single file containing all transaction types, broken down by SKU, Order, and Package level." type="success" %} {% @code-walkthrough/alert-block title="" message="One single fee invoiced for checkout services." type="success" %} {% @code-walkthrough/alert-block title="" message="One payment to reconcile." type="success" %} {% @code-walkthrough/alert-block title="" message="Select the currencies that suit you while ESW handles all FX exposure." type="success" %} {% @code-walkthrough/alert-block title="" message=" A dedicated ESW finance contact to assist with any payment or order queries." type="success" %} {% @code-walkthrough/alert-block title="" message=" Get reconciliation reports by email or SFTP, with on-demand analysis available in Looker." type="success" %} {% endtab %} {% endtabs %} # Settlement and Billing # Reconciliation Process Reconciliation process for settlements and billing ### Overview * ESW generates a settlement report via email or SFTP, this includes all transaction types, Sales, Returns & Refunds. This is in line with the agreed settlement period (eg weekly, fortnightly, monthly). * ESW will send an invoice for checkout & shipping fees as per the settlement report. * ESW will process the payment net of ESW Checkout fee and Shipping fee within two business days of the settlement period. Sales are included based off Shipping notification received by ESW. Returns are included once scanned and accepted into the Returns Centre. Refunds/Appeasements are included once they are approved.

### Finance Process * ESW acts as the Merchant of Record (MOR), completing sales and issuing refunds directly to the end shopper. * ESW sends the order confirmation to the shopper, using the retailer’s branding. ### ESW Reconciliation & Net Settlement Process How it works {% stepper %} {% step %} **Settlement report** ESW generates a settlement report via **email or SFTP** covering all transaction types: **Sales, Returns, and Refunds**. {% hint style="info" %} Reports follow the **agreed settlement period** — weekly, fortnightly, or monthly. {% endhint %} {% endstep %} {% step %} **Invoice issuance** ESW issues an **invoice for Checkout and Shipping fees** based on the settlement report. {% endstep %} {% step %} **Net payment timeline** ESW remits **net payment (after Checkout & Shipping fees)** within **two business days** of the settlement period. {% endstep %} {% endstepper %} {% hint style="info" icon="truck-fast" %} ## Inclusion rules * **Sales:** Included upon **Shipping Notification** received by ESW. * **Returns:** Included once **scanned and accepted into the Returns Centre**. * **Refunds/Appeasements:** Included **once approved**. {% endhint %} # Sales Sales process for settlements and billing ### Settlement Inclusion & Payment An item or order is included in the settlement once it appears in an **ASN** (Advanced Shipment Notification) file received by **ESW** within the specified timelines. Settlement runs on the chosen cadence and covers all packages shipped during the previous period.

### How It Works {% stepper %} {% step %} ### Settlement report ESW sends a settlement report to the **Retailer** showing what’s due to the retailer, with **at SKU, Order, or Package level** (via the agreed channel, e.g., email or SFTP). {% hint style="info" %} Can be **SKU / Order / Package**. {% endhint %} {% endstep %} {% step %} ### Merchandise and consumer paid shipping ESW pays the **value of merchandise and shipping** to the Retailer in the **chosen retailer base currency**. {% endstep %} {% step %} ### Duties & taxes handling ESW **retains duty and tax** and **remits them directly** to the relevant **local tax authority**. > Dependent on Jurisdiction and local tax rules. > {% endstep %} > {% endstepper %} # Returns Returns process for settlements and billing ### Settlement Inclusion & Processing A return is included in the settlement once it has been **scanned and accepted** at the retailer’s return centre during the prior period. * **ESW** processes refunds within **one working day** of acceptance at the return center. * Shoppers typically receive their refund within **5–7 working days**, depending on their bank. * These returns are reported as part of the **payment settlement file** with the retailer.

		Cover image
Refund Processing (ESW)	ESW processes refunds within one working day of acceptance at the return center.	/files/xKLiL7CbaJyIJyLJoKE5
Shopper Refund Timeline	Shoppers typically receive their refund within 5–7 working days, depending on their bank.	/files/TppsX7SuuAHhfOa0OyHv
Settlement Reporting	These returns are reported as part of the payment settlement file with the retailer.	/files/Qk9S6jaUayrZ8csEvpna

# Refunds The retailer may instruct ESW to refund any amount to the shopper outside the standard returns/cancellations process. Refunds will only be processed for items that have already shipped. If an item has not shipped, it must be refunded via the cancellation process. ### Process {% stepper %} {% step %} ### Submit Refund Request (CSP) Retailer Customer Service submits the refund in the **ESW Customer Service Portal (CSP)**. This triggers a financial transaction. Refunds can be issued at **article (SKU) level** or for the **entire order**. {% endstep %} {% step %} ### ESW Processing & Shopper Follow-up **ESW** processes all refunds. If a refund attempt fails, ESW will **retry** or notify the retailer’s customer service to **contact the shopper** directly. {% endstep %} {% step %} ### Settlement Reporting & Deductions Refunds are included in the **settlement file (via email)**. **ESW** deducts the **full amount** of approved refunds from the retailer’s settlement. {% endstep %} {% endstepper %} # Reconciliation Report Reconciliation process for settlements and billing {% columns %} {% column %} {% file src="/files/YFfhVhKegeHeF3Dw6dhN" %} {% endcolumn %} {% column %} {% file src="/files/yiWgyNb1LsMl6em6ObRj" %} {% endcolumn %} {% endcolumns %}

### Checkout Fee ESW will issue a checkout fee invoice as per the agreed contract. {% hint style="info" icon="cart-shopping" %} #### Checkout Fee Details * **ESW will issue a checkout-fee invoice** per the agreed contract, covering transaction fees, compliance, and any currency conversion. * **The invoice is itemized** in line with the settlement report, broken down by each **SKU/Package**. * **The checkout fee is a percentage** calculated on the **total basket value**. {% endhint %} ### Shipping Fee ESW will issue a shipping fee invoice as per the agreed contract. {% hint style="info" icon="boxes-stacked" %} #### Shipping Fee Details * **ESW will issue an invoice for shipping fees.** * **Package-level breakdowns** and a full summary of charges will be included in the **settlement file**. * **Shipping fees are calculated** according to the agreed **rate card** (by **Country** and **Service Level**). {% endhint %} # Pricing # Pricing Advisor Example to Settlement Follow a worked example from Pricing Advisor output to final ESW settlement, including uplift, blended duty and VAT, FX conversion, rounding, and retailer payout. {% tabs %} {% tab title="Scenario" %} #### UK shopper * **FX rate (GBP/USD):** `0.9212` * **Retailer uplift:** `+10%` applied to merchandise price in the UK. * **Duty & VAT at pre-order:** Exact values can’t be known at this stage (cart total and thresholds vary), so ESW uses a **blended (pseudo) rate** based on average cart size. * **Blended duty:** `1.6%` * **Blended VAT:** `20%` * **Rounding rule:** Prices are **rounded to the nearest** $$£0.50$$ {% endtab %} {% endtabs %} {% tabs %} {% tab title="Worked Example" %} * Merchandise price: **$200** * Uplift (10%): **$20** → Subtotal: **$220** * Estimated duty (1.6% of $220): **$3.52** * Estimated VAT (20% of $220 + duty): **$44.70** * FX conversion to GBP at `0.9212` → $$≈ £247.09$$ * **Rounded shopper price** (nearest £0.50): **£247.50**.

{% hint style="info" icon="basket-shopping" %} ESW returns these components (uplift, estimated duty, estimated VAT, FX rate, rounding rule) per country; for the UK, the example above applies. The resulting price is passed to ESW via the [**Checkout API pre-order**](/checkout-api). {% endhint %} {% endtab %} {% endtabs %} ## Customer Order Confirmation & ESW Settlement {% tabs %} {% tab title="Example" %} {% hint style="info" icon="tags" %} **Shopper view:** Total paid by shopper = **£247.50 GBP**. {% endhint %} ### ESW settlement breakdown | Line item | GBP | USD | Notes | | ------------------------- | ---------- | ---------- | --------------------------------------------------------- | | Merch | 204.21 | 221.68 | Merchandise value | | Shipping | — | — | Shipping charged to customer at checkout | | Duties | 2.04 | 2.22 | ESW remits to local authorities (actual \~1%) | | Tax | 41.25 | 44.78 | ESW remits to local authorities (actual \~20%) | | **Total** | **247.50** | **268.67** | Matches shopper total (GBP); converted value shown in USD | | **Total paid by shopper** | **247.50** | **268.67** | Confirmation of shopper payment | | ESW Checkout fee | 13.61 | 14.78 | \~ **5.50%** | | ESW Shipping Fee | 10.00 | 10.86 | As per agreed rate card | | **Retailer receives** | **180.60** | **196.04** | Settlement to retailer after ESW fees | | **Total costs** | **66.90** | **72.63** | Sum of ESW fees, duties, and tax |

{% endtab %} {% endtabs %} # Order Flow from Confirmation to Settlement # Flow to Order Confirmation & Payloads The flow of an order from confirmation to settlement involves several key steps {% stepper %} {% step %} #### Checkout & Payment Shopper selects delivery method, and enters payment details * **Delivery Method:** Standard or Express with estimated delivery dates * **Delivery Address:** Name, street, city, postal code, country, email, phone, opt-ins * **Payment:** Card details (name, number, expiry, CVV) and consent to ESW terms & policies

{% endstep %} {% step %} #### Order Confirmation * **Thank-you page** with **Order ID**, delivery window, masked payment details * **Addresses** (Delivery & Payment) and **Order Summary** (items, delivery, total) * Actions: **Save as PDF** or **Continue shopping**

{% endstep %} {% step %} #### Integration Payloads **PreOrderPayload.txt** — pricing breakdown, FX, estimated duties/VAT, cart lines {% file src="/files/k0YkNn6lRpDTI2LsmrEt" %} **OrderConfirmationPayload.txt** — final order details (order ID, shopper, items, totals, delivery method) {% file src="/files/mEzCuDytfRa1JdATFKAt" %} {% endstep %} {% endstepper %} # Order Settlement ## File Attributes {% tabs %} {% tab title="Attributes" %} * **Brand Name:** Go Casual * **Settlement File Date:** 08/09/2025 * **Transaction Date/Time:** 04/09/2025 11:37 * **Order Number:** PT1250904113524817GB * **ESW Reference:** 5.00104E+12 * **Transaction Type:** Sale * **Settlement Currency:** EUR * **Country ISO:** GB * **Gift Card Identifier / PSP Reference:** (blank in row) {% endtab %} {% endtabs %} ## Totals (per order confirmation) | Currency | Total paid by shopper | | :------: | :-------------------: | | GBP | `20.99` | | EUR | `23.51` | {% hint style="warning" icon="money-bill-transfer" %} GBP is the shopper’s charge; EUR is the retailer/settlement currency. {% endhint %} ## Basket Breakdown

Line item	GBP	EUR	Notes
Goods	12.50	14.00	Merchandise (net of tax)
Shipping	4.99	5.59	Consumer-paid shipping (net of tax)
Taxes on goods @20%	2.50	2.80	VAT on goods
Taxes on delivery @20%	1.00	1.12	VAT on shipping
Total	`20.99`	`23.51`	Matches shopper/retailer totals

* **Duty:** ESW calculates local D\&T; retained/remitted by ESW to authorities on importation (if applicable). * **Return Fee:** Deducted from settlement if applicable. * **Total Amount:** Total to be settled before fees; net of tax. * **Fee Basis:** Total basket value including taxes paid by the consumer. * **Retailer Fee:** Fee as per contract; net of tax. * **Net Amount:** Amount paid by ESW to the retailer; net of tax. ## Settlement Summary | Column | EUR | Meaning | | :--------------: | :-----: | :---------------------------------------------: | | Goods | 14.00 | Merchandise value | | Shipping | 5.59 | Shopper-paid shipping | | VAT | 3.92 | 2.80 (goods) + 1.12 (delivery) | | Duty | — | Not charged in this example | | Other Tax | — | — | | **Total Amount** | `19.59` | Goods + Shipping (ex VAT) | | **Fee Basis** | 23.51 | Total basket incl. shopper-paid taxes | | **Retailer Fee** | 1.06 | Contract fee on the fee basis | | **Net Amount** | `18.53` | Payout to retailer after fees (and remittances) | {% hint style="info" icon="calculator" %} **Total Amount (ex-VAT)** = 14.00 + 5.59 = `19.59`\ **Net Amount ≈ Total Amount - Retailer Fee** = 19.59 - 1.06 = `18.53` {% endhint %} {% code title="Payload" expandable="true" %} ```json { "retailerCartId": "PT1250904113524817GB", "shopperOrderNumber": "ce8b284a-c202-4578-affe-75cacf0d0ec0", "checkoutTotal": { "retailer": { "currency": "EUR", "amount": "23.51" }, "shopper": { "currency": "GBP", "amount": "20.99" } }, "pricingSynchronizationId": null, "paymentDetails": { "time": "2025-09-04T13:07:15.3334631Z", "method": "PaymentCard", "methodCardBrand": "Visa", "fraudHold": null, "amountPaid": "20.99", "isOverCounter": null, "ticketDetails": null }, "retailerPromoCodes": [], "lineItems": [ { "quantity": 1, "product": { "productCode": "123456789", "hsCode": "62114900", "title": "Test product", "description": "Test product description" }, "productUnitPriceInfo": { "price": { "retailer": { "currency": "EUR", "amount": "16.80" }, "shopper": { "currency": "GBP", "amount": "15.00" } } }, "discounts": [], "imageUrl": "https://i.pining.com/736x/ae/23/32/ae233275ce831208cc677538d95ed66c.jpg", "color": "Blk" } ] } ``` {% endcode %}
# Invoicing, Tax and Duties Payment # Fully Trade Compliant ESW delivers an end-to-end trade-compliance layer for global trade, handling the operational and regulatory work so merchants can sell cross-border with confidence. Product data flows through compliant pricing, tax, and documentation processes so shoppers see accurate landed costs and import/export obligations are met. ### What’s Included {% hint style="info" icon="plane-departure" %} **Trade compliance**\ ESW will handle invoicing, tax and duties payment on your behalf. {% endhint %}

# Trade Compliance Flow Follow the six-step trade compliance flow from product normalization and pricing through customs checks, documentation, and compliant invoicing. Trade compliance flow guides an order from cart to customs in six coordinated steps. At checkout, product data is normalized and classified (Step 1-2), pricing logic applies rounding and models (Step 3), and duty/tax calculators return an accurate landed cost for the shopper (Step 4). After purchase, shipping and customs steps validate trade rules and documentation (Step 5), and the system issues compliant VAT invoices, credit notes, and receipts (Step 6).

{% hint style="warning" %} ### Read more * ESW retain D\&T and pay it over to local authorities * All sales from the retailer is B2B zero rated * ESW settle back net of taxes and fees {% endhint %} # Invoicing requirements ESW invoice and credit note requirements by region, including EU, US, rest-of-world, and domestic VAT treatment. {% hint style="info" icon="bell-on" %} ## ESW requires * An **invoice** for all relevant **sales** in the settlement period, and * A **credit note** for all **returns** processed in that period. {% endhint %} ## Intra-EU * **One invoice/credit note per EU country.** * Must be **addressed to ESW** and **quote the applicable ESW VAT number** for that country. * **VAT treatment:** Invoices are **Zero-rated** for VAT purposes (B2B transaction). ## United States (US) * **One invoice/credit note** for US sales. * Must be **addressed to ESW’s US entity (EUSA)**. * **VAT/Sales Tax:** **Zero-rated for VAT purposes**. **No Sales Tax** applies to the sale to EUSA; EUSA will provide relevant **reseller exemption certificates** to the retailer. ## Rest of World (ROW) * Invoices/credit notes issued for **all non-EU countries** can be **grouped on a single document**. * Must be **addressed to ESW** and **quote ESW’s Irish VAT number**. * **VAT treatment:** Invoices/Credit Notes for all non-EU countries are **Zero-rated**. ## Domestic (Retailer’s Home Country) * For **domestic sales**, charge **VAT at the applicable local rate** on invoices/credit notes, as these constitute domestic sales. ## Sample Documentation {% columns %} {% column %} {% file src="/files/vK3oS9DIJRUSDcW5bhX0" %} {% endcolumn %} {% column %} {% file src="/files/irFaZ8MJ2RsmiQuNYA7H" %} {% endcolumn %} {% endcolumns %} # Payment Terms How ESW settlement payments work, including payout cadence, net settlement components, and how duties, taxes, sales, and returns are treated. {% stepper %} {% step %} ## Frequency ESW makes **one net payment** on your preferred cadence — **weekly, fortnightly, or monthly**. {% hint style="info" %} With ESW, you get the entire payment for each settlement period upfront—no thresholds, no cash held back, just reliable cash flow. {% endhint %} {% endstep %} {% step %} ## Basis Using your **settlement report**, ESW pays the **net value** of: * **Merchandise** * **Consumer-paid shipping** * **Returns** * **Appeasements** * **Checkout fee** * **Shipping fee** ### Read more * **Duties & taxes:** Collected from the consumer by ESW and remitted to the relevant local tax authority. * **Sales basis:** All sales values are calculated on **shipped items**. * **Returns basis:** All returns values reflect items **accepted at the returns centre**. > Dependent on Jurisdicton and local tax rules. > {% endstep %} > {% endstepper %} # EU Customs Duty Exemption How the EU’s 1 July 2026 duty changes affect low-value imports and your ESW pricing. The European Union will remove the customs duty exemption threshold for low value imports effective 1st July 2026. From this date, all goods imported into the EU will be subject to customs duty, including shipments that were previously exempt due to their value. This change applies to all imports into the European Union across all member states. This change impacts how customs duties are calculated and applied for EU-bound orders processed through ESW. ### What does this mean #### Low value orders Orders below the previous exemption threshold will now incur customs duty. A fixed duty will be applied per item within the order, with items defined by their HS code classification. #### Higher value orders Orders above the previous exemption threshold will continue to follow the existing customs duty model, where duties are calculated as a percentage based on HS code. There is no change to this approach. {% tabs %} {% tab title="Example" %} A retailer ships a parcel containing: * 1 linen shirt * 2 cashmere shirts {% endtab %} {% endtabs %} Although all items are included in one parcel, the linen and cashmere shirts are classified differently for customs purposes. The shipment would therefore attract two separate `€3` charges (`€6` total). Where multiple units share the same customs code, only one `€3` charge would apply, provided the total shipment value remains within the `€150` threshold. ### What action do I need to take If you use ESW’s [Pricing Advisor](/pricing-advisor-api) tool, you can review and confirm whether to apply the updated customs duty configuration within [ESW Checkout](/checkout-api). ESW has completed analysis and provided recommended updates within the tool. If you use Price Book values, you should review and incorporate the updated customs duty structure into your shopper pricing where applicable. ESW has provided recommended duty adjustments to support this update. {% hint style="info" icon="coins" %} **Note**: As it is a customs duty, it is reported as Duty. {% endhint %} {% tabs %} {% tab title="Suppoort" %} If you have any questions or require further guidance, please contact your Client Success Manager. {% endtab %} {% endtabs %} # FAQs and Customization Find answers to common questions about ESW’s merchant-of-record model, reporting, settlement options, and key operational definitions.

What are the advantages of using a MOR provider?

The main advantages of using a merchant of record provider are full compliance with global tax laws, reduced legal and financial liability, simplified Global expansion, stremlined payment operations and faster time to market.

What additional services do ESW offer?

ESW has a full product offering which supports our retailers globally with customized solutions and additional product offerings. Please contact a member of our sales team or [**finance\_onboarding@esw.com**](mailto:finance_onboarding@esw.com) to find out more.

Is there flexibility around ESW'S offerings?

ESW offers flexible payment terms, settlement periods and full support of your expansion.

Who is responsible for tax compliance — the retailer or the MOR?

**ESW, as MOR, is responsible for all tax compliance**, removing this burden from your team.

Can we get a breakdown of taxes collected from end customers?

Yes. Your **settlement report** shows a breakdown of all taxes collected from end customers that **ESW retains to remit to local authorities**.

Can I use ESW to sell both digital and physical products?

Yes. **ESW supports both digital and physical sales** through the platform.

How do chargebacks work with a MoR?

**ESW deals with all PSPs** and assumes the **risk related to chargebacks** as the MOR.

Will ESW support our audit process?

Yes. **ESW will support with any reports requested by statutory auditors.**

How frequently will we get paid?

**Customisable cadence** — ESW offers **weekly, fortnightly, or monthly** settlement.

Will our order reference or SKU code appear on the file?

Yes. ESW shows an **internal ESW order reference** and the **brand’s order reference**. Reporting can be provided at **SKU, package, or order level**.

Is there additional reporting available?

Yes. **Self-service reporting** is available via ESW’s **BI tool** for additional insights.

Is ESW a scalable solution?

Yes. **ESW’s shared-revenue model** aligns incentives with your **growth and cross-border expansion**.

Who will assist with any queries?

You will be **allocated a dedicated finance contact** who manages settlement and any related queries.

Who is my onboarding contact?

For onboarding, contact the **Onboarding email address** or your **Solution Engineer** assigned by ESW.

## Definitions

What is MOR?

A merchant of record is a legal entity responsible for selling goods or services to an end customer. They handle all payments and take on the associated liabilities.

Who acts as MOR

esw acts as MOR

What is EOR?

Exporter of record is an authorised person or entity that takes responsibility for the export of goods form a country, putting their name on the shipping documentation as the exporter in the country that the goods are dispatched from.

Who acts as EOR?

The retailer acts as EOR with ESW managing this on your behalf.

What is IOR?

Importer of record is the party who is responsible for ensuring that imported goods comply with all customs and legal requirements of the country of import.

Who acts as IOR?

The shopper acts as IOR in order to take advantage of deminimus thresholds.

What is SFTP?

SFTP stands for Secure File Transfer Protocol (or SSH File Transfer Protocol). It is a network protocol used to securely transfer files between two systems over an encrypted connection.

What is ASN?

Advanced Shipping Notice is an electronic notification a supplier sends to a buyer to inform them that an order has shipped.

What is SKU?

SKU stands for stock Keeping Unit. It is a unique identifier that businesses use to track products in inventory, warehouses and sales systems.

What is CSP?

CSP is ESW''s in house customer service portal.

# Best Practices This section describes the best practices and ESW recommendations that you can follow to ensure the smooth flow of data between your servers and ESW servers. ### Transport security * Expose your receiving endpoint over HTTPS. * Use a valid, publicly trusted certificate. * Ensure your server presents the full certificate chain. {% hint style="info" %} ESW verifies SSL certificates when delivering payloads. {% endhint %} ### Delivery semantics (distributed systems reality) * Expect retries on network or endpoint failures. * Do not assume strict ordering of events. * Expect duplicate deliveries in some failure modes. * Make your handlers **idempotent**. * Treat each delivery as independent and safe to process more than once. {% hint style="warning" %} ESW uses a queuing model and delivers events on a best-effort basis. Ordering is not guaranteed. {% endhint %} ### Support and troubleshooting When you contact ESW about delivery or integration issues, include: * Your environment (Sandbox or Production). * Your endpoint URL and the approximate time window. * The HTTP status codes you returned. * The response body you returned (if any). * Any request identifiers or correlation IDs (if provided). ### Rate limiting and traffic spikes Rate limits can turn a short spike into a long replay backlog. Plan for bursts. * Align provider-level throttles with your expected peak traffic. * Avoid blanket throttles that convert bursts into sustained failures (for example `429` / `5xx`). * Ensure your endpoint can absorb replay traffic after an outage. * Use internal buffering (queue/worker pattern) so you can accept deliveries quickly.

Example failure loop (what to avoid)

You launch a new product. Traffic spikes. Your provider starts throttling requests. ESW continues generating events. Deliveries fail (`429`/`5xx`). ESW queues and retries later. Retries add more traffic. Throttling continues. The queue grows for hours.

# APIs Best practices for endpoints ESW calls: authenticate requests, return correct status codes, handle retries and bursts, and acknowledge quickly. These guidelines apply to any endpoint ESW calls (APIs, callbacks, and webhooks). ### Verify requests are from ESW * Use a secret (token) to authenticate incoming requests. * Validate the token before doing any heavy work. * Store the secret securely and rotate it when needed. ### Return the right HTTP status codes Status codes drive retry behavior. Keep them accurate. * Return `2xx` only when you accept the request for processing. * Return `4xx` for client-side issues (bad payloads, failed auth). * Return `5xx` only for transient server failures you want retried. * If you return `429`, ESW will back off and retry later. {% hint style="warning" %} Do not include personally identifiable information (PII) in error responses. {% endhint %} ### Plan for retries, bursts, and duplicate deliveries * Expect retries, out-of-order delivery, and occasional duplicates. * Make handlers **idempotent** and safe to run more than once. * Size for bursts, not averages. As a rough sizing example, `50k/hour` is \~`14 requests/second` on average. Real traffic is spiky. Your actual load depends on how many event types you subscribe to. For more detail on retries and spikes, follow the guidance in [Best Practices](/getting-started/get-started-with-esw/best-practices). ### Acknowledge quickly and validate early * Always send a response to acknowledge receipt. * Do lightweight validation up front, then process asynchronously if needed. * Fail fast when you know you cannot process the request. # Webhooks Best practices for ESW webhooks: HTTPS and domain requirements, validate event type/version, respond within 3 seconds, and design for async delivery. Use these guidelines when you subscribe to ESW webhooks and implement the receiving endpoint. ### Endpoint requirements * Subscriptions must point to an **HTTPS** endpoint. ESW rejects non-HTTPS endpoints. * Webhook endpoints must be in the **same domain** as the origin checkout domain, or one of your registered domains. * Keep SSL certificates valid and maintained. ESW will not deliver to endpoints with SSL issues (mismatch, untrusted cert, etc.). ### Event types and versions * ESW supports multiple event types. Each event type can include multiple actions. * Over time, ESW may add new event types, add actions to existing event types, or release new versions. * Always check the **event type** and **event version** before processing. * Use the `Esw-Event-Type` request header to identify the received event and route it correctly. * Expect test events. Handle them safely. ### Acknowledge quickly ESW expects a response within **3 seconds** of delivering the payload. If your service takes longer, the connection is terminated and the payload is re-queued. * Do lightweight validation first. * Offload heavy work to a background job/queue. ### Delivery model and retention Webhooks are delivered asynchronously. Delays can occur within the SLA, or longer in rare cases. Do not use webhooks as a real-time event-sourcing mechanism. ESW queues undelivered events. By default, queued events are stored for **24 hours**. After that, events are dropped. {% hint style="info" %} Design for retries, occasional duplicates, and out-of-order delivery. Keep handlers idempotent. {% endhint %} # FAQs Some frequently asked questions.

What is GoCasual?

GoCasual is ESW’s test tenant. Use it to test before your production tenant is ready.

When do GoCasual credentials expire, and how do I renew them?

GoCasual credentials expire annually. To request new credentials, submit a request on the ESW integration form:

Can I store the ESW Checkout redirect URL and reuse it if the shopper returns?

Do not store and reuse the redirect URL. Create a new Checkout session when the cart changes. Each PreOrder request represents a snapshot of the cart at that time. If the cart changes, a previously generated redirect URL may not show the latest items.

How do you handle “orphan orders” when shoppers restart checkout?

Each time a shopper starts checkout, ESW creates a **PreOrder**. A PreOrder becomes an **Order** only after payment succeeds. Unpaid PreOrders do not convert into Orders.

If there is a shipping discount, will there be a promo/voucher code in the request?

The promo/voucher field is optional. Send a promo/voucher code only when the shopper enters one. Whether it displays at Checkout depends on your Checkout display configuration.

Can I use customerID as registeredProfileID?

Yes. If you do not have a separate registered profile identifier, you can reuse `customerID`.

Why do I receive “Unauthorized token for tenant code”?

This error often returns `403 Forbidden` or `401 Unauthorized`. It has two primary causes: * **Missing claim:** The access token does not contain the `TenantCode` claim. * **Mismatched claim:** The token’s `TenantCode` does not match the tenant code in the request path. For `/ACP/GOCAS/orders`, use `TenantCode: GOCAS`. Set [`client_id`](/getting-started/get-started-with-esw/readme/publish-your-docs#scopes) to `{TENANT_CODE}.client`. Explicitly assign the `TenantCode` claim to the client in the STS configuration.

# Glossary Definitions of key ESW terms across checkout, payments, logistics, and reporting. ## A - I | Term | Description | | ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Access Tokens | The identifiers used for authenticating the users and enabling them to access the API and perform a pre-dertermined set of actions. | | Acquirer | The financial institute that processes the credit / debit card payments, on behalf of ESW. | | Additional Payments Methods (APM) | The payment methods offered to the shoppers apart from the conventional payment methods. For example, PayPal, Google Pay, Apple Pay, etc. | | Admin Charge | The fee charged to administer the payment process. | | Advance Return Notification (ARN) | The document that provides detailed information about a pending return. | | Advanced Shipping Notice (ASN) | The file that is provided by the retailer to ESW describing contents of the package they are sending to ESW. Without a valid ASN, a package cannot be scanned at the ESW hub. | | API Request | An API request is a request that allows you to retrieve data from a data source, or to send data. | | API Response | An API response is a message that is sent as a response you with data retrived from a data source. | | Application Program Interface (API) | An API is a set of programming code that enables data transmission between one software product and another. It also contains the terms of this data exchange. | | Auth Code | The authorisation code for the attempted payment. | | Average Order Value (AOV) | The measure of the average value of all checkout & offline orders placed over the selected period of time. This measure includes subsequently cancelled orders. | | Base Currency | The retailer’s currency, main the one in which the retailers receive their settlements. | | Base Rate | The value in which the shipping rates are displayed to the shoppers at the checkout. | | Billing Currency | Billing Currency is the Shopper’s Currency. | | Black Friday | The Friday following the Thanksgiving day every year. | | Brand Code | The code associated with the brand of a given retailer. | | Brand Order Reference | Retailer's unique reference number for the order. | | BrandName | Name of the retailer's brand. | | Broker Manifest In (BMI) | The file that is received ESW from the broker with the updated information about the packages created within the ESW platform. | | Broker Manifest Out (BMO) | The file that is sent to the retailers with information about the packages created within the ESW platform. | | Bulk Packages | The physical packages sent to the shopper in bulk. A package might contain one or more order items. A collection of multiple packages are bulk packages. | | Business Requirement Document (BRD) | The document that highlights the business need of the customers and the business owners. BRD majorly indicates the project deliverables and the requirements and outcomes associated with each process function within the business. | | Carrier | A vendor that ESW does direct business with in the movement of packages. | | Cart | The set of items that the shopper has selected before proceeding to checkout. | | Change Request/Scope Change Request | The communication to request an addition or subtraction to the scope of work that has been previously agreed upon for a given project. | | Chargeback (CB) | The process of reversal/return of the money transfer back to the payer, in a given transaction. | | Checkout | The process in which the shopper enters their delivery address and proceeds to payment. | | Checkout API | 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. | | Checkout API | 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. | | Checkout URL | Allows users to easily clone the source for the repository at the top of the page for a Fisheye repository (Ex: for an SVN repository, a user can click Checkout and copy the URL). | | Content Delivery Cloud/Network (CDN) | The geographically distributed group of servers that work together to provide fast delivery of content on the internet. CDN enables the quick transfer of assets needed for loading web content including HTML pages, javascript files, stylesheets, images, and videos. | | Currency | The currency in which the shipping rates are displayed to the shoppers at the checkout. | | Currency Exchange Rate | The currency Exchange rate could be defined as the rate at which one currency will be exchanged for another currency. It could also be defined as the value of a country’s currency in relation to any other currency. | | Customer Service Portal (CSP) | The portal for both the customer service team and the retailer to look up orders, customer information, carrier tracking information, refunds, returns, and order details. | | Customs Catalog API | The Customs Catalog API allows retailers to share their product catalog with ESW. | | CVV | The 'Card Verification Value' (CVV) number on your credit card or debit card is a 3 digit number required to verify your card while processing a payment. | | Dangerous Goods (DG) | The articles or substances that pose a risk to people, property or the environment, due to their chemical or physical properties. These products are classified as dangerous goods and are prohibited from being stored on the airplane. | | Delivery Duty Paid (DDP) | The flag to identify if the delivery duty has been paid. | | Delivery Duty Unpaid (DDU) | The flag to identify if the delivery duty has not been paid. | | Dimensions (DIM) | The measure of the length, breadth, and the height of the package being shipped. | | Distribution Center (DC) | The specialised ESW hub that manages the storage and shipping of the goods for a retailer. Retailers can send the packages to these centres from where these packages are further sent to the shoppers by ESW. | | Domain Masking | The method of hiding the actual domain name of a website from the URL field of a web browser, and overlaying that name with another desired name. | | Duty Drawback | The refund of excise or import duty paid on goods that are exported. This refund can be in part or the full amount paid by the trader against the import duty. This includes customs duty, sales tax, and any other refundable fee levied. In countries where it is applicable, ESW reclaims the taxes from the relevant customs authorities. | | Electronice Wallet (eWallet) | The software tools that enable the users to store their payment information like credit card details and bank account details. The users can then use this information to make a payment for their online orders. | | Eshop Order Reference | ESW's unique reference number for the order. | | Eshop Package Reference | ESW's unique reference number for the package. | | Estimated Delivery Date (EDD) | The date when the shopper can expect the order to arrive. However, this date is not a guranteed date and just an estimate. | | Exporter of Record (EOR) | The legal exporting body for goods that are exiting a country. EOR is usually the owner or seller of merchandise that is being exported from a given country to a destination country. | | Express Payment Methods (EPM) | The payment method where the shoppers can use the pre-existing information with a payment service provider to facilitate a faster payment. For example, shoppers can pay through PayPal Express, where the information like billing address and other details are pre-filled and the users do not need to manually re-enter the details to successfully place an order. | | File Transfer Protocol (FTP) | The standard communication protocol used for the transfer of computer files from a server to a client over a computer network. ESW shares all the files with retailers via SFTP. | | Fraud Decision | The final decision on the payment by Fraud after a challenge response is received from fraud screening. | | Functional Requirement Document (FRD) | The formal statement of an application’s functional requirements. FRD also serves the same purpose as a contract. Under this document, the developers agree to provide the capabilities specified and the client agrees to find the product satisfactory if it provides the capabilities specified in the FRD. | | FX Rate | The comparison and statement of one currency with another to show their relative values. ESW processes FX rates (foreign exchange rates) via Pricing Advisor API. | | General Data Protection Regulation (GDPR) | The regulation in EU law on data protection and privacy for all residents, citizens, and individuals of the European Union (EU) and the European Economic Area (EEA). | | GoCasual (GOCAS) | 'GOCAS' is used as a value for the 'identifier' parameter in the request. GoCasual is ESW’s internal testing tenant. | | Goods Service Tax (GST) | The value-added tax levied on most goods and services sold for domestic consumption. The business adds the GST to the price of the product, and a shopper who buys the product pays the sales price plus GST. However, it is remitted to the government by the businesses selling the goods and services. | | Google Tag Manager (GTM) | The tool that enables you you to manage and deploy marketing tags on your website or mobile app. This allows you to have a good control over your analytics and measurement tag configurations from a web-based user interface. | | Harmonized System Code (HS Code) | The standardized international system to classify globally traded products. The harmonized system code (HS Code) categorizes about 5,000 commodity groups in simple six-digit codes, broken down into 21 Harmonized System sections, 96 Harmonized System chapters, and thousands of headings. This classification highlights whether an item sold internationally is apparel, fragrance, cosmetics, etc. | | Hub | The specialised ESW centre that manages the storage and shipping of the goods for a retailer. Retailers can send the packages to these centres from where these packages are further sent to the shoppers by ESW. | | Item Sub Total | The total payable amount before the absolute total for an item in an order. This total does not include the duties, taxes, discounts, and other such payable entities. | ## J - R | Term | Description | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Local Acquirer | The local acquirer is a financial institution that locally processes a payment. For example, AstroPay in Chile and Mexico, and Iyzico in Turkey. | | Magento App | The Magento App extension integration allows retailers to get access to a network of 25+ global carriers, 40+ global hubs, multiple PSPs and acquirers, 40+ payment methods, 100+ currencies, multilingual checkout, and much more. | | Master Airway Bill (MAWB) | MAWB is issued by main carrier of goods on receipt of goods from a freight forwarder to deliver at destination as per agreed terms. | | Max Order Value Limit | The maximum limit of the order value for which a different shipping rate can be set per checkout total. | | Merchant ID (MID) | The ID associated with the merchant. | | Multichannel | The marketing approach with the goal of maximizing opportunities to interact with prospective customers using various channels. These channels can be email, print advertisement, retail location, website, promotional event, mobile app, SMS messaging, product’s package, or word-of-mouth. | | Omnichannel | The method in which a business offers different modes of shopping to the shoppers. The different modes can be: online, physical shop, phone, etc. | | Order | The order placed by a shopper on the ESW checkout page. An order is considered to be complete only when the payment for the order is confirmed and the order confirmation page is displayed. | | Order API | The Order API contains the POST, GET, and PUT methods that allow you to perform a variety of tasks, such as canceling full order, canceling a line item within the order, issuing replacements (full or partial), issuing order appeasements (full or partial), issue line item appeasements (full or partial), get a specific transaction for an order, update contact details on the order. | | Order Management System (OMS) | The tool that tracks orders, sales, inventory, and fulfillment as well as allows the stakeholders to manage the orders from the shoppers. | | Order Reference | The reference number associated with an order. | | Order Value | The total value of the order, including the shipping cost and duty and taxes. | | Orders | The order placed by a shopper on the ESW checkout page. An order is considered to be complete only when the payment for the order is confirmed and the order confirmation page is displayed. | | Package | The physical package sent to the shopper. A package might contain one or more order items. | | Package API | The Package API is a web API that allows you to inject package data into the ESW system and enter all details needed for the shipment and delivery of these packages, for example, package dimensions, weight information, consignee details, item details, and so on. | | Package Dimension Source | The source from where the package dimensions like length, width, and height are determined. | | Package Dimensional Weight | The measure of package dimensional weight. | | Package Dimensional Weight Unit | The unit in which the package dimensional weight is measured. | | Package Dimensions Unit | The unit in which the package dimensions are measured. | | Payment Amount | The amount paid that is the price of product, delivery cost, uplift, duty, and taxes. | | Payment Currency | Currency in which the payment is made. | | Payment Details | The payment details on the package, for example, name, phone number, email address. | | Payment Gateway | The payment gateway used for making a payment. | | Payment Method | The method used by the shopper to make a payment, for example, credit or debit card. | | Payment Service Provider | The vendors that process the shopper’s online payment via different avenues like debit cards, credit cards, bank transfers, etc. | | Pending Payments | The payments that are yet to be completed and not deemed as 'Successful'. | | Pre-Order | The point where the shopper clicks on "Checkout" button on retailer site, that is when the PreOrder payload is built and sent to ESW. This payload includes cart information as well as the shopper and retailer configuration details. | | Pricing Advisor API | ESW’s Pricing Advisor API v3.0 allows you to retrieve pricing data for countries where you want to sell your products. | | Product Code | The code number associated with the product (also known as SKU number). | | Product Detail Page (PDP) | The website page that has details about a given product. | | Product ID | The ID reference associated with the product in the catalog. This is essentially same as Product Code and SKU number. | | Purchase Order (PO) | The document generated by the buyer that authorizes a purchase transaction. When a seller accepts this document, it becomes a contract binding on both parties. This document identifies a specific seller and provides the descriptions, quantities, prices, discounts, payment terms, date of performance or shipment, and other associated terms and conditions. | | Refunded Amount | The amount that has been refunded to the shopper. | | Rest of the world (ROW) |

The countries that are not ‘Spotlight Countries’ can be grouped together under the Rest of World (ROW) category.

There are no differences in the way how country management works in either Spotlight or Rest Of the World (ROW) countries. The only difference is the way in which the countries are grouped for display and accessibility.

| | Retailer Currency | The base currency of the retailer. | | RetailerCartId | The unique order number or unique cart identifier for the retailer. | | Return Item | This refers to an individual item, purchased as part of an order, that is being returned. This is generally what the retailers will want visibility on. | | Return label | It is a label attached to the package being returned by the shopper in order to facilitate the reverse logistic (from shopper to retailer). | | Returned Order (RO) | The process where a shopper returns an order to the retailer and in turn receives a refund in the original form of payment, exchange for another item, or a store credit. | | Returns API | ESW’s Returns API v2.0 allows retailers to retrieve an order from the database and check whether it is eligible for a return, create a return order and optionally, request a return label, update an existing return order, retrieve return information, and create returns for orders/packages that could not be delivered to the shopper. | | Returns Report | The report that enlists the details of the returned sales. This report helps in understanding why clients are unhappy with their purchases by analysing the reasons for their returns. | | RFM Analysis |

RFM analysis allows you to segment customers by the frequency and value of purchases and identify those customers who spend the most money.

Recency: how long it’s been since a customer bought something from you
Frequency: how often a customer buys from you
Monetary value: the total value of purchases a customer has made

According to these metrics, it is possible to divide your customers into groups to understand which customers buy lots of things frequently, who buys few things but frequently, and who haven’t bought anything for a long time.

As a rule, only a small percentage of customers respond to general promotional offers. RFM is an excellent segmentation method for predicting customer responses, improving interactions, and increasing profits. RFM uses customer behavior data to determine how to work with each customer group.

| ## S - Z | Term | Description | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Salesforce Commerce Cloud (SFCC) |

The highly scalable, cloud-based software-as-a-service (SaaS) ecommerce solution that offers the features and functionality to provide a highly optimised ecommerce experience.

SFCC provides a rich set of capabilities, including marketing, merchandising, content, promotions, customer service, fulfillment, and artificial intelligence, for supplementing the shopping experiences.

| | Salesforce Commerce Cloud (SFCC) App | The Salesforce Commerce Cloud (SFCC) - ESW cartridge allows you to integrate with the ESW services, such as hosted checkout, local payment methods, and international logistics network. | | Scope of Work (SOW) | The document that provides information on the technical and service deliverables that are to be provided by ESW to the retailer in order to provide a localized shopping experience to retailer’s international shoppers. Once approved by the retailer, this document is used by ESW to configure the platform and implement the agreed functionalities. | | Service Level Agreement (SLA) | The initial service level agreed by the retailer to ship the package once the order is placed. This usually falls into either a standard or express category. | | Service Type | Postal service. | | Service-level Agreement (SLA) | The initial service level agreed by the retailer to ship the package once the order is placed. This usually falls into either a standard or express category. | | Shipping Methods | Various methods using which a package is shipped to the shoppers. For example, by post, express, standard, etc. | | Shopify App | The ESW-Shopify app is an app developed by ESW for retailers using Shopify as their eCommerce platform. The app extends a retailer’s current market reach by allowing them to integrate with ESW's optimized services, such as FX rates, hosted checkout with local payment options, and international logistics network. The ESW-Shopify app supports all versions of Shopify - Basic, Standard, Advanced, and Plus. | | Shopper | The individual who makes a purchase via a retailer’s website and makes a payment for the purchase to receive the order. | | Shopper Service Level 1 | The level 1 Shopper Service entails ESW Shopper Service team responding directly to “post checkout” shopper queries. These typically relate to Tracking queries and Return/refund query. | | Shopper Service Level 2 | The level 2 Shopper Service entails ESW Shopper Service team responding directly to “post checkout” retailer queries. The retailer CS team interact directly with the shopper, and escalate queries when required, to the ESW team. Responses from ESW CS team will respond directly to the retailer CS team. These typically relate to Tracking queries and Return/refund query. | | Spotlight countries |

Spotlight countries are your top countries that are displayed on the ESW Service Portal’s country management screen for quick access. You can spotlight a country that you are looking to grow into for quicker access to its configurations.

| | Standard Operating Procedure (SOP) | The written, step-by-step instructions that describe how to perform a routine activity; in this case engaging with ESW. Standard operating procedures help in maintaining safety and efficiency for the individual departments that come together to form an organization. | | Stock-Keeping Unit (SKU) | The stock keeping unit is a unique product in a retailer’s catalog. | | Sub Total | The total payable amount before the absolute total for the order. This total does not include the duties, taxes, discounts, and other such payable entities. | | Tenant Code | The six-digit code associated with the tenant. | | Total Orphan Payments | The payments which have been successfully completed but do not have an order linked to them. | | Tracking information |

The information that consists of the details around the events occurring during the transit and receipt of the return package from the shopper to you.

The tracking info you see on ESW Service Portal will mainly consist of the following details:

Order Number
Last Location
Last Updated
The time when a particular event occurred.
Description of the event.
The location where the event occurred.

| | Undeliverable | The package that a carrier has attempted last mile delivery but was unsuccessful for whatever reason. | | Unsettled Amount | The total amount that has not been claimed by the retailer and is no more on hold. | | Value Added Tax (VAT) | The tax placed on a product whenever value is added at each stage of the supply chain, from production to the point of sale. This tax is based around taxpayer's consumption of the goods. | | Weight | Total weight of the order package. | | Weight Unit | The unit in which the weight of the package is measured. | | Zone | The dedicated set of regions from where orders are placed and that is reported to the retailers by ESW. | # Copy of Overview Start here to explore ESW APIs and jump to the main service areas, including customs, pricing, checkout, orders, returns, callbacks, and fulfillment. {% hint style="info" icon="file-brackets-curly" %} #### ESW services are delivered and managed via REST APIs. Expect resource-oriented URLs and JSON payloads. {% endhint %}


Customs Catalog API	Pricing Advisor API	Checkout API	Package API
Order API	Returns API	Callback API	Fulfillment API

Customs Catalog API

Pricing Advisor API

{% columns %} {% column valign="middle" %} {% hint style="info" icon="shirt" %}

Customs Catalog

{% endhint %}

{% hint style="info" icon="laptop" %} Order {% endhint %}

{% endcolumn %} {% column valign="middle" %} {% hint style="info" icon="chart-mixed" %}

Pricing Advisor

{% endhint %}

{% hint style="info" icon="arrow-rotate-right" %} Returns {% endhint %}

{% endcolumn %} {% column valign="middle" %} {% hint style="info" icon="basket-shopping" %} Checkout {% endhint %}

{% hint style="info" icon="webhook" %} Callback {% endhint %}

{% endcolumn %} {% column valign="middle" %} {% hint style="info" icon="box-open" %} Package {% endhint %}

{% hint style="info" icon="location-dot" %} Fulfillment {% endhint %}

{% endcolumn %} {% endcolumns %}

# Authentication Learn how ESW STS authentication works, how to request OAuth 2.0 access tokens with client credentials, and how to send Bearer tokens on API requests. ESW APIs use the **Security Token Service (STS)**. STS issues and validates **OAuth 2.0 access tokens**. You pass these tokens as **Bearer** tokens on every API request. Most integrations use the **OAuth 2.0 client credentials** flow. You authenticate with a `client_id` and `client_secret`. You exchange them for a short-lived access token from STS. ### How authentication works {% stepper %} {% step %} #### Request an access token from STS **STS token endpoint** `POST` `https://security-sts..eshopworld.com/connect/token` Exchange your `client_id` + `client_secret` for OAuth 2.0 access token. **Headers** | Name | Value | | ------------ | ----------------------------------- | | Content-Type | `application/x-www-form-urlencoded` | **Body** (form URL encoded) | Name | Type | Description | | --------------- | ------ | ----------------------------------------------------------------------------------- | | `grant_type` | string | Use `client_credentials` | | `scope` | string | Space-separated scopes Example: `checkout.preorder.api.all pricing.advisor.api.all` | | `client_id` | string | Client identifier provided by ESW | | `client_secret` | string | Client secret provided by ESW | **Response** {% tabs %} {% tab title="200" %} ```json { "access_token": "", "expires_in": 3600, "token_type": "Bearer", "scope": "checkout.preorder.api.all" } ``` {% endtab %} {% tab title="403" %} ```json { "error": "invalid_client", "error_description": "Client credentials are invalid." } ``` {% endtab %} {% endtabs %} Use the examples on [Access Tokens](/getting-started/get-started-with-esw/readme/publish-your-docs). {% endstep %} {% step %} #### Call ESW APIs with the Bearer token Send the token in the `Authorization` header: ```http Authorization: Bearer ``` If the token is missing or invalid, you will get `401` or `403`. {% endstep %} {% endstepper %} ### Client credentials ESW provides your credentials via a secure channel during setup. You use them only when requesting tokens from STS. * **Client ID**: A unique identifier assigned to a client. * **Client secret**: A unique secret assigned to a client. Your client secret is private and you must keep your client secret confidential. Client credentials are valid for **six months**. There is a **one-month rollover** window for rotating secrets. {% hint style="warning" icon="key" %} Treat the client secret like a password. Store it in a secrets manager or encrypted store. Never commit it to source control or share it in tickets. {% endhint %} ### Token lifetime and renewal STS returns `expires_in` in the token response. Cache tokens and reuse them until they expire. Request a new token when you get `401` and the token is expired. ### OAuth / OpenID Connect notes STS is compatible with **OAuth 2.0** and **OpenID Connect**. See the external reference: [OAuth 2.0](https://oauth.net/2/). # Access Tokens Request OAuth 2.0 access tokens from ESW STS using client credentials. Includes required parameters, token endpoint, and code examples. Request OAuth 2.0 access tokens from the ESW **Security Token Service (STS)**. Most integrations use: * `grant_type=client_credentials` * one or more space-separated `scope` values ### Token endpoint Send a `POST` to: `https://security-sts..eshopworld.com/connect/token` {% hint style="info" icon="brackets-curly" %} STS expects `application/x-www-form-urlencoded` body parameters. {% endhint %} ### Parameters Include these fields in the request body: * `grant_type`: OAuth 2.0 grant type. Use `client_credentials`. * `scope`: Space-separated scopes. Example: `checkout.preorder.api.all`, `pricing.advisor.api.all` * `client_id`: Client identifier provided by ESW. * `client_secret`: Client secret provided by ESW. ### Examples {% tabs %} {% tab title="cURL" %} ```sh curl --location --request POST "https://security-sts..eshopworld.com/connect/token" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "grant_type=client_credentials" \ --data-urlencode "scope=" \ --data-urlencode "client_id=" \ --data-urlencode "client_secret=" ``` {% endtab %} {% tab title="C# (RestSharp)" %} ```csharp var client = new RestClient("https://security-sts..eshopworld.com/connect/token"); var request = new RestRequest("", Method.Post); request.AddHeader("Content-Type", "application/x-www-form-urlencoded"); request.AddParameter("grant_type", "client_credentials"); request.AddParameter("scope", ""); request.AddParameter("client_id", ""); request.AddParameter("client_secret", ""); var response = client.Execute(request); Console.WriteLine(response.Content); ``` {% endtab %} {% tab title="Java (OkHttp)" %} ```java OkHttpClient client = new OkHttpClient(); RequestBody body = new FormBody.Builder() .add("grant_type", "client_credentials") .add("scope", "") .add("client_id", "") .add("client_secret", "") .build(); Request request = new Request.Builder() .url("https://security-sts..eshopworld.com/connect/token") .post(body) .build(); Response response = client.newCall(request).execute(); System.out.println(response.body().string()); ``` {% endtab %} {% endtabs %} See the [Postman collection](/getting-started/get-started-with-esw/readme/postman-collection#get-the-postman-collection) for working sandbox examples. ### Access Token Response STS returns the access token and the token type (usually `Bearer`). ```json { "access_token": "eyJhbGciOiJSUzI1NiIsImtpZC...I6IjQ3NkQ1QzE5QzI1Nzc0NUV", "expires_in": 3600, "token_type": "Bearer", "scope": "checkout.preorder.api.all" } ``` ### Use the token Send the token on API requests: ```http Authorization: Bearer ``` For the full flow, see [Authentication](/getting-started/get-started-with-esw/readme/quickstart). # Postman Collection Download and import the ESW Postman collection + environment to run the sandbox flow (token → PreOrder → redirect). ### Get the Postman collection Postman is the fastest way to explore the sandbox flow. 1. Install [Postman](https://www.getpostman.com/downloads/) 2. Import the files below. 3. Select the imported environment. 4. Run the requests in order `(token → PreOrder → redirect)` Our Postman collection contains a series of Checkout API calls that are made during a typical Checkout session. The URLs in these environments point to the Integration Layer Proxy, which further points to GoCasual by default. Note that each environment contains STS tokens for the equivalent GoCasual API. **Collection** (requests) {% file src="/files/gGjk9sLNbPezX9HQAgzB" %} **Environment** (variables) {% file src="/files/1nIW6uTGFgmaDGoj0bEt" %} ### Try Checkout end-to-end #### Test credentials (sandbox) Use these values when requesting an STS token in sandbox. | Field | Value | | --------------- | ----------------------------------------------------------- | | Token URL | `https://security-sts.sandbox.eshopworld.com/connect/token` | | `grant_type` | `client_credentials` | | `scope` | `checkout.preorder.api.all` | | `client_id` | `gocas.checkout.client` | | `client_secret` | Provided by ESW | {% stepper %} {% step %} #### Get an STS access token Use the same pattern as on [Access Tokens](/getting-started/get-started-with-esw/readme/publish-your-docs). ```sh curl --location --request POST "https://security-sts.sandbox.eshopworld.com/connect/token" \ --header "Content-Type: application/x-www-form-urlencoded" \ --data-urlencode "grant_type=client_credentials" \ --data-urlencode "scope=checkout.preorder.api.all" \ --data-urlencode "client_id=" \ --data-urlencode "client_secret=" ``` **Sample response** ```json { "access_token": "", "expires_in": 3600, "token_type": "Bearer", "scope": "checkout.preorder.api.all" } ``` {% endstep %} {% step %} #### Create a PreOrder Use the `access_token` from the previous step. {% code expandable="true" %} ```sh curl --location --request POST "https://checkout-api-gocas.sandbox.eshopworld.com/api/v2/PreOrder" \ --header "Content-Type: application/json" \ --header "Authorization: Bearer " \ --data-raw '{ "retailerCartId": "Sample123", "cartItems": [ { "quantity": 2, "product": { "productCode": "1234567890", "title": "Black Dress", "description": "Black Striped Dress", "shopperCurrencyProductPriceInfo": { "price": "AUD3.33" }, "imageUrl": "assets/images/cart/cart-item10.png", "color": "Black", "size": "M" }, "cartGrouping": "Group 1" } ], "shopperCurrencyIso": "AUD", "retailerCurrencyIso": "EUR", "deliveryCountryIso": "AU" }' ``` {% endcode %} **Sample API Response** ```json { "preOrderCode": "e23afa68-9675-4012-8d63-df1517c624cc", "orderNumber": "e23afa68-9675-4012-8d63-df1517c624cc", "redirectUrl": "https://checkout-ui.sandbox.eshopworld.com/au/e23afa68-9675-4012-8d63-df1517c624cc" } ``` {% endstep %} {% step %} #### Open Checkout Open `redirectUrl` in a browser. {% endstep %} {% endstepper %} ### Troubleshooting * `401/403`: token missing, expired, or wrong `scope`. See [Authentication](/getting-started/get-started-with-esw/readme/quickstart). * `400`: request body validation failed. Start by reducing to one item. * Slow responses / timeouts: follow [API best practices](/getting-started/get-started-with-esw/best-practices/apis). # Test Cards Test card numbers for validating ESW Checkout payments, including non-3DS and 3DS scenarios (Adyen and Computop) with OTP notes. ### Non-3DS Test Cards The following are the details of the test cards that can be used to test ESW Checkout experience: | Card Type | Card Number | Expiry Date | Security Code | | :------------------------------------------------------------------------------: | :-----------------: | :---------: | :-----------: | |

American Express | 3700 0000 0000 002 | 03/2030 | 7373 | |

Visa | 4111 1111 1111 1111 | 03/2030 | 737 | |

Mastercard | 5555 4444 3333 1111 | 03/2030 | 737 | |

Diners | 3600 6666 3333 44 | 03/2030 | 737 | |

Discover | 6445 6445 6445 6445 | 03/2030 | 737 | |

JCB | 3569 9900 1009 5841 | 03/2030 | 737 | |

China UnionPay | 6240 0086 3140 114 | 03/2030 | 737 | |

Electron | 4400 0000 0000 0000 | 03/2030 | 737 | |

Maestro | 6771 7980 2100 0008 | 08/2029 | 737 | |

China UnionPay | 6250 9470 0000 0014 | 03/2030 | 123 | |

Troy | 9792 0300 0000 0000 | 08/2029 | 737 | *** ### 3DS Test Cards You can test the 3DS Computop cards using the following details: |

Visa

Mastercard

Test Scenario

Adyen Cards {% hint style="info" icon="credit-card" %} * The Adyen cards are enrolled in 3D Secure 2 security framework. To test 3D Secure 2 (advanced) scenarios, refer to [test 3D Secure 2 authentication](https://docs.adyen.com/development-resources/testing/3d-secure-2-authentication). * One time password (OTP): 1234 {% endhint %} | American Express | 3714 4963 5398 431 | Mar-30 | 7373 | | :---------------------------: | :-----------------: | :----: | :------------: | | Bancontact / Maestro | 6703 4444 4444 4449 | Mar-30 | Not applicable | | Bancontact / Visa | 4871 0499 9999 9910 | Mar-30 | 737 | | Cartes Bancaires / Visa Debit | 4035 5014 2814 6300 | Mar-30 | 737 | | Cartes Bancaires | 4360 0000 0100 0005 | Mar-30 | 737 | | China UnionPay (Credit) | 6250 9470 0000 0014 | Mar-30 | 123 | | China UnionPay (Debit) | 6250 9460 0000 0016 | Mar-30 | 123 | | Diners | 3056 9309 0259 04 | Mar-30 | 737 | | Discover | 6011 1111 1111 1117 | Mar-30 | 737 | | Maestro | 5000 5500 0000 0029 | Mar-30 | Not applicable | | Mastercard | 5555 4444 3333 1111 | Mar-30 | 737 | | Mastercard Credit | 2222 4000 1000 0008 | Mar-30 | 737 | | Visa | 4917 6100 0000 0000 | Mar-30 | 737 | | Visa Classic | 4166 6766 6766 6746 | Mar-30 | 737 | *** ### Computop Cards {% hint style="info" icon="binary" %} One-time password (OTP): 1234 {% endhint %} | Test Scenario | Visa | Visa/ Cartes Bancaires (co-badged) | MasterCard | MasterCard/ Cartes Bancaires (co-badged) | Maestro | Amex | | -------------------------------------------------------------------------- | ------------------- | ---------------------------------- | ------------------- | ---------------------------------------- | ------------------- | ------------------ | | Browser challenge | 4000 0164 3594 0133 | 4972 0212 3456 7842 | 5232 1221 8930 1469 | 5341 0112 3456 7851 | | 3782 8224 6310 005 | | Browser challenge | 4000 0128 9268 8323 | 4972 0212 3456 7891 | 5232 1251 2540 1459 | 5341 0112 3456 7810 | 6759 6498 2643 8453 | 3714 4963 5398 431 | | Browser frictionless; missing DS Transaction ID | 4000 01269 9048 523 | 4972 0212 3456 7883 | 5232 1272 6463 7786 | 5341 0112 3456 7893 | | | | Not authenticated browser frictionless | 4000 0117 4413 5012 | 4972 0212 3456 7834 | 5232 1227 4150 7017 | 5341 0112 3456 7844 | | | | Authenticated browser frictionless | 4000 0199 6619 9434 | 4972 0212 3456 7875 | 5232 1224 2254 3299 | 5341 0112 3456 7885 | | 3750 0000 0000 007 | | Browser challenge missing ACS URL | 4000 0155 7319 8637 | 4972 0212 3456 7826 | 5232 1280 8394 4791 | 5341 0112 3456 7836 | | | | Authentication protocol error | 4000 0178 7348 5953 | 4972 0212 3456 7867 | 5232 1225 9690 7270 | 5341 0112 3456 7877 | | | | Browser challenge; authenticated transaction; missing authentication value | 4000 0147 3036 6880 | 4972 0212 3456 7818 | 5232 1241 0698 7982 | 5341 0112 3456 7828 | | | # Core Integrations What you integrate for an end-to-end ESW implementation: Catalog, Checkout, and Package. ESW’s platform is modular by design, which means that it offers the flexibility to integrate with only the components that fit your requirements. However, if you are integrating end-to-end with ESW, then you must integrate with the three major components: Catalog, Checkout, and Shipping. ## Custom Catalog {% columns %} {% column width="16.666666666666664%" %}

{% endcolumn %} {% column width="83.33333333333334%" valign="middle" %} {% hint style="info" icon="rectangle-api" %} [Customs Catalog API](/customs-catalog-api) {% endhint %} Integrate product catalog with ESW using the Customs Catalog API or Excel `xlsx` or CSV `csv` file. Refer to [Catalog Integration](#catalog-integration) {% endcolumn %} {% endcolumns %} *** ## Checkout {% columns %} {% column width="16.666666666666664%" %}

{% endcolumn %} {% column width="83.33333333333334%" valign="middle" %} {% hint style="info" icon="rectangle-api" %} [Checkout API](/checkout-api) {% endhint %} Integrate checkout using the Checkout API or our commerce platform connectors for Magento, Salesforce Commerce Cloud or Shopify. Refer to [Checkout Integration](#checkout-integration) {% endcolumn %} {% endcolumns %} *** ## Shipping {% columns %} {% column width="16.666666666666664%" %}

{% endcolumn %} {% column width="83.33333333333334%" valign="middle" %} {% hint style="info" icon="rectangle-api" %} [Package API](/package-api) {% endhint %} Share the package data with ESW using the Package API or an `XML` file. Refer to [Shipping Integration](#shipping-integration) {% endcolumn %} {% endcolumns %} *** {% tabs %} {% tab title="Catalog integration" %} Provide your product catalog to ESW before selling internationally. ESW uses this data to calculate duties and taxes. It also supports export compliance and customs clearance. Your catalog typically includes the product code, description, country of origin, weight, and HS code. Submit the initial catalog during onboarding. ESW stores it for future calculations and validations. When product data changes, submit a complete catalog. Do not submit delta-only updates. Choose one integration method: [**Customs Catalog API**](/customs-catalog-api) Upload new catalogs and update existing ones with the `POST` endpoint. [**Catalog file transfer**](/integrations/integrations/catalog-file-integration) Upload an Excel or CSV file through SFTP. ESW provides the required format, naming convention, and location during onboarding. {% endtab %} {% tab title="Checkout integration" %} Integrate with ESW Checkout through the Checkout API or a supported commerce platform extension. [**Checkout API**](https://developer.esw.com/checkout-api/) Send the shopper’s cart to ESW. Redirect the shopper using the URL in the API response. Use the `POST` endpoint to include cart-level or order-level discounts and promotion codes. **Commerce Platform Connectors** Use the Magento plugin or Salesforce Commerce Cloud cartridge. Shopify stores can use the ESW-Shopify app. [**Light Touch Integration**](/integrations/integrations/light-touch-integration) Connect BigCommerce, WooCommerce, Commerce Tools, web storefronts, or Callback API with LTI. {% endtab %} {% tab title="Shipping integration" %} Share order and package information with ESW to synchronize shipping data. Create an **Advanced Shipping Notice (ASN)** for each package. The ASN confirms the items that the package contains. Send the ASN before the package leaves your distribution centre. ESW must receive it before the package reaches an ESW hub. Choose one integration method: [**Package API**](/package-api) Send the order number, item quantities and descriptions, weight, and dimensions. Retrieve an existing package with the `GET` endpoint. [**XML file**](/integrations/integrations/package-file-integration) Generate an XML file in the ESW format. Upload it through SFTP on an agreed schedule. {% endtab %} {% endtabs %} # API Integration Integration Summary {% stepper %} {% step %} #### Customs Catalog {% embed url="" %} {% hint style="info" icon="arrow-up-to-dotted-line" %} Choose from two upload options. {% endhint %}


Catalog file transfer	Upload an Excel `.xlsx` or CSV `.csv` file.	/pages/ynpF9DEIIZo2dkAQnVtM
Catalog API	Use the `POST` method to upload a new catalog or update an existing catalog.	/spaces/JWssSKqn34oo0GTi1dVW/pages/nIFCOrckGRjiOHBVM8Sj

{% endstep %} {% step %} #### Pricing {% embed url="" %}


Pricing Advisor API	Apply the pricing formula to calculate product prices in the shopper’s currency.	/spaces/nTL8tl9tUOtaGkSQHGiK/pages/5O83zdt3ftsRIn5w2HE3

{% endstep %} {% step %} #### Checkout {% embed url="" %}


Checkout API	Also known as the PreOrder API, sends cart information to ESW Checkout system.	/spaces/chjZv79baUiFWxjmZavx/pages/mCWQ5A8Kq5jMqZwsZXyq

{% endstep %} {% step %} #### Order {% embed url="" %}


Order API	Central order management layer in the ESW cross-border commerce platform.	/spaces/9sJh9mebwGhWfzKvcTnt/pages/PEK4qwopvAt70p01AeIx

{% endstep %} {% step %} #### Package {% embed url="" %}


Package API	Manage shipment and delivery data efficiently.	/spaces/ZhcwGHfYyTPT5VkoQl32/pages/4c24e961c980bd6a81469b55ff7abfb609f33945

{% endstep %} {% step %} #### Fulfillment {% embed url="" %}


Fulfillment API	Enable automated, real-time exchange of catalog, inventory, order, and shipment data across platforms.	/spaces/OA1tnmF5u1Lk9QuR6ayG/pages/ORi0M8U9B1scFJYIPq2F

{% endstep %} {% step %} #### Returns {% embed url="" %}


GRP Returns API	Central integration layer for ESW's Global Returns Platform	/spaces/a921jcoPME0jDOOuVtoT/pages/t4fyNGgFIcCWyiReueRm

{% endstep %} {% endstepper %} # Catalog File Integration How to name, format, and deliver Excel/CSV catalog files to ESW via SFTP, including required fields. Use the Catalog file to send your product master data to ESW. ESW uses this data for duties/taxes calculations and customs validation. You can upload either an **Excel `.xlsx`** file or a **CSV `.csv`** file. Deliver files to an ESW-provided **SFTP** location.

	Link	Cover image	Cover image (dark)
File Processing What to expect after upload, plus sample templates.	/spaces/bB3UcHnWX3RLHHoolsLd/pages/7ea0dc635c01fd18bf934c6efe780f45ffbed488	/files/gMYsvBEHgaaDHKZgKM4r	/files/kjbJbJR7abG5u3N5s4SG
Sample Customs Catalog Template Download a starter file and `enum` values	/spaces/bB3UcHnWX3RLHHoolsLd/pages/5XnBNID38K8vApYWe0ax	/files/XCzeUsZZ5xMCqiOK8gzc	/files/3MBubEJJZmNSZKxvVECM

### File naming Use this format: * `Catalog-nnn-xxxxxxxx.xlsx` * `Catalog-nnn-xxxxxxxx.csv` Where: * `nnn`: the ESW-provided brand code. * `xxxxxxxx`: an 8-digit, zero-padded counter starting at `00000001`. Example: `Catalog-ABC-00000001.xlsx` ### Generation and delivery * Agree the delivery schedule with ESW (daily, weekly, etc.). * Include records for **one brand/retailer** per file. * Keep the sequence increasing for each new file you send. {% hint style="info" %} ESW provides SFTP connection details (host, username, password) during onboarding. {% endhint %} ### Upload modes ESW can process both full loads and delta uploads. Agree the approach with ESW. * **Full catalog**: recommended for first upload and for major refreshes. * **New products only**: include only SKUs not yet in ESW. * **Updates to existing products**: include only SKUs you want to change. * On successful processing, populated fields overwrite previously stored values. ### File format rules {% tabs %} {% tab title="Excel (.xlsx)" %} * Use **one worksheet** only. * Put **one product per row**. * Row 1 must be the **header row**. * Use header names exactly as defined in [Field reference](#field-reference). * Do not include HTML tags or markup in any field. {% endtab %} {% tab title="CSV (.csv)" %} * Choose a delimiter: comma `,`, semicolon `;`, or pipe `|`. Agree this with ESW. * Use the same delimiter for the header and all data rows. * Quote fields when they contain the delimiter (standard CSV rules). * Put **one product per row**. * Do not include HTML tags or markup in any field. * Avoid trailing empty records at the end of the file. {% endtab %} {% endtabs %} ### Data rules * Use **English** values only. * Use one row to represent one product. * Use stable identifiers. `productCode` is the primary key. * If you model variants in the file, add differentiators (for example `size`) and use `variantProductCode` where applicable. ### Field reference

Field	Type	Description	Notes
`productCode`	String (50)	`Required` Brand unique master identifier or SKU. Examples: `1231321313`, `ABC-1234`, `2132132323 1`	Key identifier. Use the product SKU where possible. Keep it searchable and consistent across the retailer site, checkout, and shipping.
`name`	String (150)	`Required` Product name. Examples: `Cubania Shirt`, `10" High-Rise Skinny Jeans in Indigo Dye Wash`, `LOVELY MASCARA`	Match the product landing page title. For variants, include a distinguishing value such as color or size.
`description`	String (100)	`Required` Short product description. Examples: `women’s trousers (woven)`, `A soft, lightweight, and breathable Cubania shirt`, `high glow lipstick`	Use a concise customs-ready description. This field is used for customs clearance.
`material`	String (100)	`Required` Material composition of the product. Examples: `90% cotton, 10% silk`, `Premium 95% cotton/3% poly/2% elastane ISKO™ denim`, `Aqua (Water), Paraffin, Glyceryl Stearate`	List the primary material first. You can add up to two secondary materials. This field is used for customs clearance.
`countryOfOrigin`	CountryIso	`Required` Two-letter ISO code for the country where the product is manufactured. Examples: `CN`, `US`
`hsCode`	String (12)	`Required` Brand HS code for the product. Use 8 to 12 digits. Example: `62310100`	Keep HS code length consistent across products in the same file.
`hsCodeRegion`	Region	`Required` ESW region for the related `hsCode`. Examples: `EU`, `US`
`category`	Category	`Optional` ESW category ID for the product. Example: `ApparelClothingNotKnitted`	Recommended when you know the best category match.
`gender`	Gender	`Optional` Gender value for the product. Examples: `Female`, `Male`	Use for a single product with multiple variants.
`ageGroup`	AgeGroup	`Optional` Age group for the product. Examples: `Adult`, `Kids`	Use for a single product with multiple variants.
`size`	String (100)	`Optional` Product size. Examples: `Small`, `Large`, `32D`, `XXL`	Use for a single product with multiple variants.
`weight`	Decimal	`Optional` Product weight in the related `weightUnit`. Example: `1.00`	Use the product weight without packaging. Conditional If `weightUnit` is present, `weight` is required.
`weightUnit`	WeightUnit	`Optional` Unit for `weight`. Examples: `Kg`, `Lb`	Conditional If `weight` is present, `weightUnit` is required.
`url`	String (200)	`Optional` Product landing page URL.	Use a verified domain. Start with `http://` or `https://`. Required for specific destinations This field is required when shipping to Russia or Japan.
`imageUrl`	String (200)	`Optional` URL for the product’s main image thumbnail.	Link to the main product image thumbnail. Start with `http://` or `https://`.
`unitPrice`	Decimal	`Optional` Product price. Example: `2.69`	Submit the accurate selling price, not an approximate value. Conditional If `unitPriceCurrencyIso` is present, `unitPrice` is required.
`unitPriceCurrencyIso`	CurrencyIso	`Optional` ISO currency for `unitPrice`. Example: `EUR`	Use a valid ISO currency code. Conditional If `unitPrice` is present, `unitPriceCurrencyIso` is required.
`dangerousGoods`	Boolean	`Optional` Indicates whether the product is classified as dangerous goods or hazardous material. Accepted values: `TRUE`, `FALSE`	Items that can cause damage, harm, or injury are not allowed.
`additionalProductCode`	String (50)	`Optional` Additional product identifier, such as a manufacturer SKU.	Use when you need a secondary searchable identifier. Keep it consistent across checkout and shipping.
`variantProductCode`	String (50)	`Optional` Variant-level version of the brand master identifier or SKU.	Use when product variants need their own identifier. Keep it consistent across checkout and shipping.
`isRestricted`	Boolean	`Optional` Identifies whether the product is restricted, independent of destination or other attributes. Accepted values: `TRUE`, `FALSE`
`MID`	String (500)	`Optional` Manufacturer or shipper identification code.	Conditional This field is required for shipments to or from the US when the order value is `$800` or more.
`MIDAddressZip`	String (500)	`Optional` Merchant registered address ZIP or postal code.	Conditional This field is required when `MID` is present and `countryOfOrigin` is `CN` or `VN`. Full MID address details are mandatory when `countryOfOrigin` is `VN`.
`AdditionalInformation`	String (200)	`Optional` Extra catalog details.
`CategoryInformation`	String (200)	`Optional` Additional data that categorizes the retailer’s goods or services.
`IsSubscription`	Boolean	`Optional` Indicates whether the product can be bought as part of a subscription. Accepted values: `TRUE`, `FALSE`
`IsCustomized`	Boolean	`Optional` Indicates whether the product is customized. Accepted values: `TRUE`, `FALSE`
`eccn`	String (5)	`Optional` Export Control Classification Number for consumer electronics.	Conditional `eccn` is required in several cases, including export or re-export flows, shipments to certain countries, dual-use items, and sensitive technologies.
`ean`	String (13)	`Optional` Product identifier used for catalog matching and downstream system reference. This is not a mandatory customs attribute.	Used for product identification only. If supplied EAN must be 13 numeric digits. Only one of `EAN` or `UPC` is required per product. If both are provided, ESW prioritizes `EAN`. If neither is supplied, customs processing can still proceed if all other mandatory catalog fields are present.
`upc`	String (12)	`Optional` Product identifier used for catalog matching and downstream system reference. This is not a mandatory customs attribute.	Used for product identification only. If supplied UPC must be 12 numeric digits. Only one of `EAN` or `UPC` is required per product. If both are provided, ESW prioritizes `EAN`. If neither is supplied, customs processing can still proceed if all other mandatory catalog fields are present.

# Sample Customs Catalog Template Download a sample customs catalog template and reference allowed enum values for file-based catalog uploads. Use this sample file as a starting point for a file-based customs catalog upload. ### Download the template {% file src="/files/3hMy3LFK5vZrgH4E3jJV" %} {% @code-walkthrough/alert-block title="Enum Values" message="Enum values can be case-sensitive. Send them exactly as shown." type="error" %} ### Enumerations ### `WeightUnit` Use uppercase values. | Value | | ----- | | `LB` | | `KG` | ### `Gender` | Value | | -------- | | `Male` | | `Female` | | `Unisex` | ### `AgeGroup` | Value | Description | | --------- | ------------------- | | `Newborn` | Up to 3 months old. | | `Infant` | 3–18 months old. | | `Toddler` | 1.5–5 years old. | | `Kids` | 6–12 years old. | | `Adult` | Teens or older. | ### `Category` Use these values for the `category` field.

Show category values

| Value | | --------------------------------------------------------------- | | `AircraftSpacecraft` | | `AlbuminoidalSubstances` | | `AluminumAndArticlesThereof` | | `AnimalsPetSupplies` | | `ApparelAccessories` | | `ApparelClothingKnitted` | | `ApparelClothingNotKnitted` | | `ArmsAndAmmunition` | | `ArticlesOfIronSteel` | | `ArticlesOfLeather` | | `ArticlesOfStone` | | `ArtsEntertainment` | | `BabyToddler` | | `BusinessIndustrial` | | `CamerasOptics` | | `CarpetsAndFloorCoverings` | | `CeramicProducts` | | `ClocksAndWatches` | | `CompleteIndustrialPlant` | | `CopperAndArticlesThereof` | | `Cork` | | `Cotton` | | `Digital` | | `ElectricalMachinerySoundAndTv` | | `Electronics` | | `ExplosivesEtc` | | `FeathersAndDownArticlesAndArtificialFlowers` | | `FoodBeveragesTobacco` | | `Footwear` | | `Furniture` | | `FurnitureAndFurnishings` | | `FurskinsAndArtificialFur` | | `GlassAndGlassware` | | `Hardware` | | `Headgear` | | `HealthBeauty` | | `HomeGarden` | | `IndustrialTextileFabricsAndTextileArticles` | | `IronAndSteel` | | `KnittedCrochetedFabrics` | | `LeadAndArticlesThereof` | | `LuggageBags` | | `ManMadeFilaments` | | `ManMadeStapleFibres` | | `ManufacturesOfStrawBasketwareAndWickerwork` | | `Mature` | | `Media` | | `MiscellaneousArticlesOfBaseMetal` | | `MiscellaneousChemicalProducts` | | `MiscellaneousManufacturedArticles` | | `MusicalInstruments` | | `NickelAndArticlesThereof` | | `NuclearReactorsBoilersMachinery` | | `OfficeSupplies` | | `OpticalPhotographicCinematographicMeasuringMedicalInstruments` | | `OtherBaseMetalsAndArticlesThereof` | | `OtherMadeupWornTextileArticles` | | `OtherVegetableTextileFibres` | | `PaperAndPaperboard` | | `PerfumeryCosmeticToiletPreparations` | | `PhotographicCinematographicGoods` | | `Plastics` | | `PreciousStonesMetalsAndJewelry` | | `PrintedBooksNewspapers` | | `PulpOfWoodScrapPaperPaperboard` | | `RailwayTramwayLocomotivesRollingStock` | | `RawHidesAndSkins` | | `ReligiousCeremonial` | | `Returns label` | | `Rubber` | | `ShipsBoatsAndFloatingStructures` | | `Silk` | | `SoapPolishCandlesEtc` | | `Software` | | `SpecialCombinedNomenclatureCodes` | | `SpecialWovenFabrics` | | `SportingGoods` | | `TinAndArticlesThereof` | | `ToolsImplementsCutlery` | | `ToysGames` | | `ToysGamesAndSports` | | `UmbrellasAndWalkingSticks` | | `VehiclesOtherThanRailwayTramwayRollingStock` | | `VehiclesParts` | | `WaddingSpecialYarnsTwine` | | `Wood` | | `WoolAndAnimalHair` | | `WorksOfArtAndAntiques` | | `ZincAndArticlesThereof` |

### `CurrencyIso` Use standard ISO 4217 currency codes. Examples: `USD`, `EUR`, `GBP`.

Show CurrencyIso values

| Code | Currency | | ---- | --------------------------- | | ARS | Argentine Peso | | AUD | Australian Dollar | | AZN | Azerbaijani Manat | | BHD | Bahraini Dinar | | BDT | Bangladeshi Taka | | BBD | Barbados Dollar | | BYR | Belarusian Ruble | | BYN | Belarusian Ruble | | BZD | Belize Dollar | | BMD | Bermudian Dollar | | BOB | Boliviano | | BRL | Brazilian Real | | BGN | Bulgarian Lev | | KHR | Cambodian Riel | | CAD | Canadian Dollar | | CLP | Chilean Peso | | CNY | Chinese Yuan | | COP | Colombian Peso | | CRC | Costa Rican Colon | | HRK | Croatian Kuna | | CZK | Czech Koruna | | DKK | Danish Krone | | DOP | Dominican Peso | | EGP | Egyptian Pound | | EUR | Euro | | GIP | Gibraltar Pound | | GTQ | Guatemalan Quetzal | | HNL | Honduran Lempira | | HKD | Hong Kong Dollar | | HUF | Hungarian Forint | | INR | Indian Rupee | | IDR | Indonesian Rupiah | | ILS | Israeli New Shekel | | JMD | Jamaican Dollar | | JPY | Japanese Yen | | JOD | Jordanian Dinar | | KZT | Kazakhstani Tenge | | KWD | Kuwaiti Dinar | | LVL | Latvian Lats | | LTL | Lithuanian Litas | | MYR | Malaysian Ringgit | | MVR | Maldivian Rufiyaa | | MXN | Mexican Peso | | MDL | Moldovan Leu | | TWD | New Taiwan Dollar | | NZD | New Zealand Dollar | | NIO | Nicaraguan Córdoba | | NOK | Norwegian Krone | | OMR | Omani Rial | | PKR | Pakistani Rupee | | PAB | Panamanian Balboa | | PYG | Paraguayan Guaraní | | PEN | Peruvian Nuevo Sol | | PHP | Philippine Peso | | PLN | Polish Zloty | | GBP | Pound Sterling | | QAR | Qatari Riyal | | ROL | Romanian Leu | | RON | Romanian New Leu | | RUB | Russian Ruble | | SAR | Saudi Riyal | | SGD | Singapore Dollar | | ZAR | South African Rand | | KRW | South Korean Won | | LKR | Sri Lankan Rupee | | SEK | Swedish Krona/Kronor | | CHF | Swiss Franc | | THB | Thai Baht | | TRY | Turkish Lira | | UAH | Ukrainian Hryvnia | | AED | United Arab Emirates Dirham | | USD | United States Dollar | | VEF | Venezuelan Bolívar | | VND | Vietnamese Dong |

### `Region` Use the HS code region agreed with ESW. Common values include `EU` and `US`.

Show region values

| Code | Country | | ---- | ------------------------ | | AE | United Arab Emirates | | AL | Albania | | AU | Australia | | BA | Bosnia and Herzegovina | | BH | Bahrain | | CA | Canada | | CH | Switzerland | | CL | Chile | | CN | China | | CO | Columbia | | EG | Egypt | | EU | European Union | | GE | Georgia | | HK | Hong Kong | | ID | Indonesia | | IL | Israel | | IN | India | | JP | Japan | | KR | Korea, Republic of | | KW | Kuwait | | MA | Morocco | | MD | Moldova | | MX | Mexico | | MY | Malaysia | | NO | Norway | | NZ | New Zealand | | PH | Philippines | | PR | Puerto Rico | | QA | Qatar | | RU | Russian Federation | | SA | Saudi Arabia | | SG | Singapore | | TH | Thailand | | TR | Turkey | | TW | Taiwan | | US | United States of America | | VN | Vietnam | | ZA | South Africa |

#### `CountryIso` Use ISO 3166-1 alpha-2 country codes. Examples: `US`, `CN`, `GB`.

Show CountryIso values

| Code | Country/Region | | ---- | ------------------------------------------- | | AF | Afghanistan | | AX | Aland Islands | | AL | Albania | | DZ | Algeria | | AS | American Samoa | | AD | Andorra | | AO | Angola | | AI | Anguilla | | AQ | Antarctica | | AG | Antigua and Barbuda | | AR | Argentina | | AM | Armenia | | AW | Aruba | | AU | Australia | | AT | Austria | | AZ | Azerbaijan | | BS | Bahamas | | BH | Bahrain | | BD | Bangladesh | | BB | Barbados | | BY | Belarus | | BE | Belgium | | BZ | Belize | | BJ | Benin | | BM | Bermuda | | BT | Bhutan | | BO | Bolivia | | BQ | Bonaire, Sint Eustatius and Saba | | BA | Bosnia and Herzegovina | | BW | Botswana | | BV | Bouvet Island | | BR | Brazil | | IO | British Indian Ocean Territory | | VG | British Virgin Islands (UK | | BN | Brunei Darussalam | | BG | Bulgaria | | BF | Burkina Faso | | BI | Burundi | | KH | Cambodia | | CM | Cameroon | | CA | Canada | | CV | Cape Verde | | KY | Cayman Islands (UK) | | CF | Central African Republic | | TD | Chad | | CL | Chile | | CN | China | | CX | Christmas Island | | CC | Cocos (Keeling) Islands | | CO | Colombia | | KM | Comoros | | CG | Congo | | CD | Congo, Democratic Republic of the | | CK | Cook Islands | | CR | Costa Rica | | CI | Côte D'Ivoire | | HR | Croatia | | CU | Cuba | | CW | Curaçao | | CY | Cyprus | | CZ | Czech Republic | | DK | Denmark | | DJ | Djibouti | | DM | Dominica | | DO | Dominican Republic | | EC | Ecuador | | EG | Egypt | | SV | El Salvador | | GQ | Equatorial Guinea | | ER | Eritrea | | EE | Estonia | | ET | Ethiopia | | FK | Falkland Islands | | FO | Faroe Islands | | FJ | Fiji | | FI | Finland | | FR | France | | GF | French Guiana | | PF | French Polynesia | | TF | French Southern Territories | | GA | Gabon | | GM | Gambia | | GE | Georgia | | DE | Germany | | GH | Ghana | | GI | Gibraltar | | GR | Greece | | GL | Greenland | | GD | Grenada | | GP | Guadeloupe | | GU | Guam | | GT | Guatemala | | GG | Guernsey | | GN | Guinea | | GW | Guinea-Bissau | | GY | Guyana | | HT | Haiti | | HM | Heard Island and McDonald Islands | | VA | Holy See (Vatican City) | | HN | Honduras | | HK | Hong Kong | | HU | Hungary | | IS | Iceland | | IN | India | | ID | Indonesia | | IR | Iran | | IQ | Iraq | | IE | Ireland | | IM | Isle of Man | | IL | Israel | | IT | Italy | | JM | Jamaica | | JP | Japan | | JE | Jersey | | JO | Jordan | | KZ | Kazakhstan | | KE | Kenya | | KI | Kiribati | | KP | Korea, Democratic People's Republic (North) | | KR | Korea, Republic of (South) | | KW | Kuwait | | KG | Kyrgyzstan | | LA | Laos | | LV | Latvia | | LB | Lebanon | | LS | Lesotho | | LR | Liberia | | LY | Libya | | LI | Liechtenstein | | LT | Lithuania | | LU | Luxembourg | | MO | Macau | | MK | Macedonia | | MG | Madagascar | | MW | Malawi | | MY | Malaysia | | MV | Maldives | | ML | Mali | | MT | Malta | | MH | Marshall Islands | | MQ | Martinique (FR) | | MR | Mauritania | | MU | Mauritius | | YT | Mayotte (FR) | | MX | Mexico | | FM | Micronesia, Federated States of | | MD | Moldova Republic of | | MC | Monaco | | MN | Mongolia | | ME | Montenegro | | MS | Montserrat | | MA | Morocco | | MZ | Mozambique | | MM | Myanmar | | NA | Namibia | | NR | Nauru | | NP | Nepal | | NL | Netherlands | | NC | New Caledonia | | NZ | New Zealand | | NI | Nicaragua | | NE | Niger | | NG | Nigeria | | NU | Niue | | NF | Norfolk Island | | MP | Northern Mariana Islands | | NO | Norway | | OM | Oman | | PK | Pakistan | | PW | Palau | | PS | Palestinian Territories | | PA | Panama | | PG | Papua New Guinea | | PY | Paraguay | | PE | Peru | | PH | Philippines | | PN | Pitcairn Islands | | PL | Poland | | PT | Portugal | | PR | Puerto Rico | | QA | Qatar | | RE | Reunion | | RO | Romania | | RU | Russia | | RW | Rwanda | | BL | Saint Barthelemy | | SH | Saint Helena | | KN | Saint Kitts and Nevis | | LC | Saint Lucia | | MF | Saint Martin | | PM | Saint Pierre & Miquelon | | VC | Saint Vincent and the Grenadines | | WS | Samoa | | SM | San Marino | | ST | Sao Tome and Principe | | SA | Saudi Arabia | | SN | Senegal | | RS | Serbia | | SC | Seychelles | | SL | Sierra Leone | | SG | Singapore | | SX | Sint Maarten | | SK | Slovakia | | SI | Slovenia | | SB | Solomon Islands | | SO | Somalia | | ZA | South Africa | | GS | South Georgia & South Sandwich Islands | | SS | South Sudan | | ES | Spain | | LK | Sri Lanka | | SD | Sudan | | SR | Suriname | | SJ | Svalbard and Jan Mayen | | SZ | Swaziland | | SE | Sweden | | CH | Switzerland | | SY | Syria | | TW | Taiwan | | TJ | Tajikistan | | TZ | Tanzania | | TH | Thailand | | TL | Timor-Leste | | TG | Togo | | TK | Tokelau | | TO | Tonga | | TT | Trinidad and Tobago | | TN | Tunisia | | TR | Turkey | | TM | Turkmenistan | | TC | Turks and Caicos Islands | | TV | Tuvalu | | UG | Uganda | | UA | Ukraine | | AE | United Arab Emirates | | GB | United Kingdom | | US | United States | | UM | United States Minor Outlying Islands | | UY | Uruguay | | UZ | Uzbekistan | | VU | Vanuatu | | VE | Venezuela | | VN | Vietnam | | VI | Virgin Islands | | WF | Wallis and Futuna | | EH | Western Sahara | | YE | Yemen | | ZM | Zambia | | ZW | Zimbabwe |

# File Processing Understand file processing notifications and download sample templates for Excel, CSV, customs catalog, and sales report uploads. ### Processing results After ESW processes your file, it sends a success/failure notification to the ESW Trade Compliance Team. Each notification includes the validation status for every catalog item. If a file fails validation, fix the data and resubmit the file. ### Example templates Download sample templates for each format and publication year. {% tabs %} {% tab title="Excel" %} #### **Minimum catalog file** **Publication year:** 2024 (latest) {% file src="/files/8ZFtuqXo53FmG2i91en4" %} **Publication year:** 2022 {% file src="/files/ZmbPpcAsz7Y9alLbFQeq" %} *** #### **Full catalog file** **Publication year:** 2024 (latest) {% file src="/files/XOttyC61cGaN5SmL6oTt" %} **Publication year:** 2022 {% file src="/files/Hs9zsU1s19zHCRvoQUHa" %} *** #### **Delta catalog file** **Publication year:** 2024 (latest) {% file src="/files/wJfBRVTYyGrMju88AftN" %} **Publication year:** 2022 {% file src="/files/Qr5MgrrhVSep7ekMV63Q" %} {% endtab %} {% tab title="CSV (Using Comma Delimiter)" %} #### **Minimum catalog file** **Publication year:** 2024 (latest) {% file src="/files/DFkjjbYuhqyVy2tcDXEx" %} **Publication year:** 2022 {% file src="/files/g4cJjBUb0kjZeJtlyhJ8" %} *** #### **Full catalog file** **Publication year:** 2024 (latest) {% file src="/files/f1VQOn6fj4swamwb6hWj" %} **Publication year:** 2022 {% file src="/files/RKTY2jdBQRsdnvZnr6bS" %} *** #### **Delta catalog file** **Publication year:** 2024 (latest) {% file src="/files/PBGFHYYKK6iGPXqqnWUA" %} **Publication year:** 2022 {% file src="/files/R53Y3BoOeTMy4kvWMaC0" %} {% endtab %} {% endtabs %} ### Customs catalog and sales report templates Use these templates when uploading files in the ESW wizard during self-serve brand setup. They show the expected columns and formatting. {% tabs %} {% tab title="Customs catalog template" %} {% file src="/files/3hMy3LFK5vZrgH4E3jJV" %} {% endtab %} {% tab title="Sales report template" %} {% file src="/files/yW0UR9sy22rAT4BBkHMA" %} {% endtab %} {% endtabs %} # Package File Integration How to name, format, and deliver XML package files to ESW via SFTP, including required fields. Use the Package file to send package and item data to ESW in batches. One file can contain many packages. If you also send catalog data by SFTP, keep the naming and sequencing rules consistent across feeds. ### File naming Use this format: * `Package-nnn-xxxxxxxx.xml` Where: * `nnn`: the ESW-provided brand code. * `xxxxxxxx`: an 8-digit, zero-padded counter starting at `00000001`. Example: `Package-123-00000001.xml` ### Delivery (SFTP) * Upload files to an ESW-provided SFTP folder. * Agree the delivery schedule with ESW (hourly, daily, etc.). * Keep the sequence increasing for each new file you send. * Do not re-use a file name. Send a new file after fixes. {% hint style="info" %} ESW provides SFTP connection details (host, username, password) during onboarding. {% endhint %} ### File format rules * XML must be well-formed and encoded as UTF-8. * Use a single root node: ``. * Include one `` node per package. * Element names and casing must match the agreed schema. * Omit optional elements when you have no value (preferred over sending empty tags). After upload, ESW processes the file and returns a success/failure notification. See [File Processing](/integrations/integrations/catalog-file-integration/file-processing). ### Example XML

Show example XML

{% hint style="warning" %} Use element names exactly as shown. XML element names are case-sensitive. {% endhint %} ```xml 123 DUB1 ORDER-10001 ORDER-10001 PKG-00000001 TRACKING-123 false Jane Doe jane.doe@example.com +3531234567 1 Main St Dublin D01 ABC2 IE CHECKOUT 4.15 EUR 1.2 Kg 10 30 20 Cm Apparel POST SKU-001 1 T-shirt 100% cotton t-shirt CN 0.3 Kg 25.00 EUR 610910 NEW ```

### Field reference {% hint style="info" %} Some fields are required only for specific order flows (for example non-checkout orders). Confirm your exact requirements with ESW during onboarding. {% endhint %}

Package

| Element | Type | Required | Notes | | ------------------------ | ------------- | ----------- | ----------------------------------------------------------------------------------- | | `BrandCode` | string (3) | Yes | ESW-provided identifier for the brand/retailer. | | `WareHouse` | string (200) | No | Warehouse shipping location identifier. | | `OrderReference` | string (30) | Yes | Unique order reference for the package. | | `OriginalOrderReference` | string (30) | No | Parent order reference for backorders or split shipments. | | `PackageReference` | string (50) | Yes | Unique package reference. | | `CarrierReference` | string (50) | No | Carrier tracking/reference number. | | `IsBackOrder` | boolean | No | Set `true` when this is not the first package for the order. | | `Consignee` | object | Conditional | Optional for checkout; required for non-checkout orders. | | `OrderType` | string / enum | Yes | Order flow identifier (for example `CHECKOUT`). Use the ESW-agreed values. | | `ShippingInfo` | object | Yes | Shipping charge details. | | `Weight` | object | Yes | Total package weight. | | `Dimensions` | object | Yes | Package dimensions. | | `GoodsDescription` | string (100) | Yes | High-level description of goods. | | `ServiceLevel` | string / enum | Conditional | Optional for checkout; required for non-checkout orders. Use the ESW-agreed values. | | `PackageItems` | object | Yes | Container for one or more `PackageItem` nodes. | | `PackageStatus` | string / enum | Yes | Package status (for example `NEW`). Use the ESW-agreed values. |

Consignee

| Element | Type | Required | Notes | | ------------ | ------------ | -------- | ------------------------------------------- | | `FirstName` | string (70) | Yes | Recipient first name. | | `LastName` | string (70) | Yes | Recipient last name. | | `Gender` | string (6) | No | Recipient gender. | | `Email` | string (100) | Yes | Recipient email address. | | `Telephone` | string (150) | Yes | Recipient phone number. | | `Unit` | string (100) | No | Apartment/unit/suite. | | `Address1` | string (150) | Yes | Address line 1. | | `Address2` | string (150) | No | Address line 2. | | `Address3` | string (150) | No | Address line 3. | | `City` | string (100) | Yes | City. | | `PostalCode` | string (50) | Yes | Postcode or ZIP. | | `POBox` | string (50) | No | PO box. | | `Region` | string (150) | No | State/province/region. | | `Country` | string (2) | Yes | ISO 3166-1 alpha-2 code (for example `JP`). |

ShippingInfo

| Element | Type | Required | Notes | | ------------------------ | ---------- | -------- | -------------------------------------- | | `ShippingChargeValue` | decimal | No | Shipping amount (for example `4.15`). | | `ShippingChargeCurrency` | string (3) | No | ISO 4217 currency (for example `EUR`). |

Weight

| Element | Type | Required | Notes | | ------------- | ------------- | -------- | --------------------------------------------------------------------- | | `WeightTotal` | decimal | Yes | Total package weight. | | `WeightUnit` | string / enum | Yes | Unit for `WeightTotal` (for example `Kg`). Use the ESW-agreed values. |

Dimensions

| Element | Type | Required | Notes | | -------------------- | ------------- | -------- | ------------------------------------------------------------------------ | | `DimHeight` | decimal | No | Package height. | | `DimLength` | decimal | No | Package length. | | `DimWidth` | decimal | No | Package width. | | `DimensionalWeight` | decimal | No | Dimensional weight if provided. | | `DimMeasurementUnit` | string / enum | No | Unit for dimensions (for example `In`, `Cm`). Use the ESW-agreed values. |

PackageItem

| Element | Type | Required | Notes | | --------------------------- | ------------- | ----------- | ------------------------------------------------------------------------------- | | `ProductCode` | string (50) | Yes | Retailer SKU or product code. | | `Quantity` | integer | Yes | Quantity for this `ProductCode` at the same `UnitPrice`. | | `ProductDescription` | string (150) | Conditional | Optional for checkout; required for non-checkout orders. | | `ProductCustomsDescription` | string (150) | Conditional | Optional for checkout; required for non-checkout orders. | | `CountryOfOrigin` | string (2) | Conditional | Optional for checkout; required for non-checkout orders. ISO 3166-1 alpha-2. | | `Weight` | decimal | Yes | Item weight. | | `WeightUnit` | string / enum | Yes | Unit for item `Weight` (for example `Kg`). Use the ESW-agreed values. | | `UnitPrice` | decimal | Conditional | Optional for checkout; required for non-checkout orders. Price after discounts. | | `UnitPriceCurrency` | string (3) | Conditional | Required when `UnitPrice` is present. ISO 4217 (for example `EUR`). | | `HsCode` | string (20) | Conditional | Optional for checkout; required for non-checkout orders. |

# Tracking XML File Spec Schema and delivery rules for ESW tracking outbound XML files. Use the Tracking outbound file to receive package tracking events from ESW. ESW generates files on a schedule and drops them to SFTP. {% hint style="info" icon="file-xml" %} * The tracking event records will be supplied as a delta of the previous file. * ESW will never send the same tracking event for any package more than once. {% endhint %} ### Delta behavior * Each file contains only new tracking events since the previous file. * ESW does not send the same tracking event for the same package more than once. * Process files in sequence and persist the last processed counter. ### File naming Use this format: * `Tracking-nnnnnnnn-xxxxxxxx:xml` Where: * `nnnnnnnn:` your ESW customer number. * `xxxxxxxx`: an 8-digit, zero-padded counter starting at `00000001`. Example: `Tracking-1004-00000001.xml` ### Delivery (SFTP) * ESW provides an SFTP folder for tracking outbound files. * Agree the generation frequency with ESW (for example hourly or daily). * Each file contains records for one brand/retailer. {% hint style="warning" icon="memo-circle-check" %} ESW provides SFTP connection details (host, username, password) during onboarding. {% endhint %} ### File format rules * XML must be well-formed and encoded as UTF-8. * Root node: ``. * The file contains one `

` and one or more `` nodes. * Omit optional elements when you have no value (preferred over sending empty tags). ### Field reference #### Header

Show header fields

| Element | Type | Required | Notes | | -------------- | ----------- | -------- | ---------------------------------------------------------------------------------- | | `Version` | string | Yes | File version. Always `2.05`. | | `RecordCount` | integer | Yes | Number of `` records in the file. | | `FileDateTime` | string (16) | Yes | File creation timestamp. Format: `YYYY-MM-DD HH:MM` (24-hour). | | `TimeZone` | string (3) | Yes | Timezone for `FileDateTime` (for example `UTC`). | | `FileName` | string | Yes | File name including extension. Format: `Tracking--.xml`. |

#### TrackingEvent

Show TrackingEvent fields

| Element | Type | Required | Notes | | -------------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------ | | `CustomerOrderReference` | string (20) | Yes | Your order reference. | | `CustomerPackageReference` | string (20) | No | Your package reference. | | `EswOrderReference` | string (20) | No | ESW order reference. | | `EswPackageReference` | string (20) | No | ESW package reference. | | `EswReturnOrderReference` | string (20) | No | ESW return order reference (when applicable). | | `CarrierPackageReference` | string (20) | No | Carrier tracking/reference number. | | `EventCode` | string (20) | Yes | Event code from the [Event codes](#event-codes) list. | | `EventDescription` | string (100) | Yes | Human-readable event description. | | `EventDateTime` | string (16) | Yes | Tracking event timestamp. Format: `YYYY-MM-DD HH:MM` (24-hour). | | `EventLocation` | string (50) | Yes | Location in `Town/City, CC` format, where `CC` is ISO 3166-1 alpha-2 (for example `London, GB`). |

#### Example XML

Show example XML

```xml

2.05 2 2013-01-25 14:56 UTC Tracking-1004-00000001.xml

12345678901234567810 123456789012345678 5001000000001 6001000000001 200100123 12345678901234567810 ESW0000015 Shipment Delivered - J.Smith 2013-01-25 14:56 London, GB 12345678901234567811 123456789012345679 5001000000002 6001000000002 200100124 12345678901234567811 ESW0000008 Departed Origin Country 2013-01-27 17:16 New York, US ```

#### Event codes The following table shows the meaning of each `EventCode` value.

Show event codes

| EventCode | Description | Short Description | | ---------- | -------------------------------------------------------------------- | -------------------------------------------------- | | ESW0000001 | Order pending ID details collection | Pending ID Details | | ESW0000002 | ID Details received or submitted by Shopper | Released - consignee Information Received | | ESW0000003 | Shipment is on hold at origin waiting for CD\&T payment | Pending Customs, Duty & Tax Payment | | ESW0000004 | Payment received or Retailer requested to release | Released - Payment received | | ESW0000005 | Shipment left the retailer warehouse | Shipped | | ESW0000006 | Shipment arrived to International forwarder at origin | Arrived International Hub | | ESW0000007 | Shipment left international forwarder and tendered to Airlines | Departed International Hub | | ESW0000008 | Shipment had departed on flight to destination country | Departed Origin Country | | ESW0000009 | Shipment arrived to the port of Destination country | Arrived at Transit Hub | | ESW0000010 | Shipment forwarded to Destination country | In Transit to Destination Country | | ESW0000011 | Shipment arrived to final destination country | Arrived Destination Country | | ESW0000012 | Shipment held in customs for check and release | Pending customs release | | ESW0000013 | Shipment customs released | Customs Released | | ESW0000014 | Shipment is out for Delivery with Driver | Out for Delivery | | ESW0000015 | Shipment Delivered/Picked up/dropped at post box/ | Delivered | | ESW0000016 | Delivery failed due to various reasons (address, Phone…) | Attempted Delivery | | ESW0000017 | Shipment returned from destination country back to port of Entry | Return to Sender | | ESW0000019 | Shipment can't be delivered due to various reasons | Undelivered | | ESW0000020 | Shipment on hold waiting for an action from Shopper or Shipper | On Hold | | ESW0000021 | Operational delay, carrier fault (Misrouted, missed delivery slot…) | Delay/Misrouted | | ESW0000022 | Delay caused by Weather, Bank Holiday, Act of God… | Uncontrollable Delay | | ESW0000023 | Shipment sent to destination under a new tracking Ref. | Redirected under a new reference | | ESW0000024 | Shipment has been sent to a different delivery address | Redirected to another destination | | ESW0000025 | General Tracking Update | General Update | | ESW0000026 | Shipment was not received at destination port or destination country | Short at Arrival | | ESW0000027 | Shipment destroyed upon shipper request | Destroyed | | ESW0000028 | Short Shipped | ASN Received - Package Missing | | ESW0000029 | Damaged - can't be delivered | Carton Arrived Damaged - Return to Vendor | | ESW0000030 | Damaged - forwarded under new packaging | Carton Arrived Damaged - Repackaged | | ESW0000031 | Shipment received, can be forwarded | Carton Arrived OK | | ESW0000032 | Delay in Line | Carton Arrived Damaged - Repackaged | | ESW0000033 | Shipment Overage | Carton Arrived - no ASN | | ESW0000034 | Shipment stopped | Carton Arrived - Stop Flag set | | ESW0000035 | Shipment stopped | Carton Arrived - Stop - Other | | ESW0000036 | Duplicate Shipment | Carton Arrived - Duplicate package | | ESW0000037 | Incorrect Address | Carton Arrived - Address failure | | ESW0000038 | Package has been labelled and ready for shipping | Package Received | | ESW0000039 | Package has been added to a Shipping Manifest | Shipment manifested (TMS) | | ESW0000040 | Shipment was scheduled for delivery upon Customer request | Shipment Scheduled for Delivery | | ESW0000041 | In Transit | In Transit | | ESW0000042 | Pending Shopper Pickup from Office (New Update) | Pending Shopper Pickup from Office (New Update) | | ESW0000043 | Package HOLD returned from HUB | Package HOLD returned from HUB | | ESW0000044 | Return Order Created | Return Order Created | | ESW0000045 | Return Order Arrived at RC | Return Order Arrived at RC | | ESW0000046 | COD Amount Collected | COD Amount Collected | | ESW0000047 | COD Amount Paid to Retailer (ESW) | COD Amount Paid to Retailer (ESW) | | ESW0000048 | Package lost | Package lost | | ESW0000049 | Package Repacked | Package Repacked | | ESW0000050 | Handed over to third party | Handed over to third party | | ESW0000051 | Return Label Created | Return Label Created | | ESW0000052 | Return Received by Carrier | Return Received by Carrier | | ESW0000053 | Return Inspected | Return Inspected | | ESW0000054 | Refund Issued | Refund Issued | | ESW0000055 | COD Amount Not Collected | COD Amount Not Collected | | ESW0000056 | Departed Hub | Departed Hub | | ESW0000057 | In Transit to Retailer | In Transit to Retailer | | ESW0000058 | Returned to Retailer | Returned to Retailer | | ESW0000060 | Package Declared | Package Declared | | ESW0000099 | No Internal Mapping | No Internal Mapping | | ESW0000601 | Delivered to RC | Delivered to RC | | ESW0000602 | Return not delivered to RC | Return not delivered to RC | | ESW0000603 | Processed in RC | Processed in RC | | ESW0000604 | Destruction by RC | Destruction by RC | | ESW0000605 | Delivered to Origin Hub | Delivered to Origin Hub | | ESW0000606 | Return not delivered to Origin Hub | Return not delivered to Origin Hub | | ESW0000607 | In Transit to Retailer | In Transit to Retailer | | ESW0000608 | Delivered to Retailer- Closure Event | Delivered to Retailer- Closure Event | | ESW0000620 | Return shipment Lost - Under investigation | Return shipment Lost - Under investigation | | ESW0000621 | Return shipment Lost - Claim submitted | Return shipment Lost - Claim submitted | | ESW0005100 | Package received in hub, awaiting Customer Data file | Package received in hub, awaiting Data file | | ESW0005101 | Customer Data file received, Package not received in HUB | Customer Data received, Package not received | | ESW0005102 | Delayed in fulfilment, truck delay | Delayed in fulfilment, truck delay | | ESW0005103 | Delayed in fulfilment, parcel not received | Delayed in fulfilment, parcel not received | | ESW0005104 | Delayed in fulfilment, ASN no package | Delayed in fulfilment, ASN no package | | ESW0005105 | Package received, awaiting Customer Data | Package received, awaiting Customer Data | | ESW0005106 | Retailer advised package will not be shipped, package not shipped | Package not shipped - Retailer request | | ESW0005107 | Retailer advised package will not be shipped, data not sent | Retailer advised package will not be shipped | | ESW0005108 | Label reserved, order not fulfilled | Label reserved, order not fulfilled | | ESW0005109 | BMO not received | BMO not received | | ESW0005110 | No BMO - Retailer to Action | No BMO - Retailer to Action | | ESW0005200 | Package not picked up by carrier | Package not picked up by carrier | | ESW0005201 | Hub Exception - On Hand in Hub | Hub Exception - On Hand in Hub | | ESW0005203 | Printed Not Manifested - Enquiry Lodged | Printed Not Manifested - Enquiry Lodged | | ESW0005204 | Pre Export Delay | Pre Export Delay | | ESW0005205 | Pre Export Issue | Pre Export Issue | | ESW0005206 | Released not Printed | Released not Printed | | ESW0005210 | Awaiting Shopper ID details | Awaiting Shopper ID details | | ESW0005211 | Package received, on hold due to stop flag activation | Package received, on hold | | ESW0005212 | Package received, MCO data error | Package received, MCO data error | | ESW0005213 | Package received, duplicate error | Package received, duplicate error | | ESW0005214 | Package recevied, address error | Package recevied, address error | | ESW0005215 | Processing delay in HUB | Processing delay in HUB | | ESW0005216 | Package recevied, address error | Package recevied, address error | | ESW0005217 | Awaiting Shopper ID details | Awaiting Shopper ID details | | ESW0005218 | Package received, duplicate error | Package received, duplicate error | | ESW0005219 | Carrier label applied, not manifested to Carrier | Carrier label applied, not manifested to Carrier | | ESW0005220 | Package manifested, scan to pallet event missing | Package manifested, scan to pallet event missing | | ESW0005221 | Error - DG flag in ASN, no DG packaging | Error - DG flag in ASN, no DG packaging | | ESW0005222 | Error - DG packaging, no DG flag in ASN | Error - DG packaging, no DG flag in ASN | | ESW0005223 | Error - DG in ASN, country not in scope | Error - DG in ASN, country not in scope | | ESW0005224 | Package not received from hub | Package not received from hub | | ESW0005225 | Package received, missing data | Package received, missing data | | ESW0005226 | Package on hold in HUB | Package on hold in HUB | | ESW0005227 | Package will not ship, military address prohibited | Package will not ship, military address prohibited | | ESW0005228 | Error - No DG Declaration | Error - No DG Declaration | | ESW0005229 | Error - quantity issue | Error - quantity issue | | ESW0005230 | HUB Exception - for Return to Sender | HUB Exception - for Return to Sender | | ESW0005231 | HUB Exception - for Return to Sender - No ID details | HUB Exception - Return to Sender - No ID details | | ESW0005232 | HUB Exception - for Return to Sender - Cannot ship | HUB Exception - for Return to Sender - Cannot ship | | ESW0005233 | HUB Exception - for Return to Sender - Military address | HUB Exception - Return to Sender-Military address | | ESW0005234 | HUB Exception - for Return to Sender - quantity issue | HUB Exception - Return to Sender - quantity issue | | ESW0005235 | HUB Exception - for Return to Sender - DG packaging issue | Return to Sender - DG packaging issue | | ESW0005236 | HUB Exception - for Return to Sender - DG ASN issue | HUB Exception - Return to Sender - DG ASN issue | | ESW0005237 | HUB Exception - for Return to Sender - Country not in scope DG | Return to Sender - Country not in scope DG | | ESW0005238 | HUB Exception - for Return to Sender - ID issue | HUB Exception - for Return to Sender - ID issue | | ESW0005239 | HUB Exception - for Return to Sender - general return | HUB Exception - Return to Sender - general return | | ESW0005240 | HUB Exception - for Return to Sender - Military address | HUB Exception - Return to Sender-Military address | | ESW0005241 | HUB Exception - for Return to Sender - quantity issue | HUB Exception - Return to Sender - quantity issue | | ESW0005242 | Fraud stop, returned to retailer | Fraud stop, returned to retailer | | ESW0005243 | MITI – Fraud Order | MITI – Fraud Order | | ESW0005301 | In Transit - Flight departed | In Transit - Flight departed | | ESW0005302 | In Transit - Flight arrived | In Transit - Flight arrived | | ESW0005303 | Transit Delay - Technical issue, 1 day delay | Transit Delay - Technical issue, 1 day delay | | ESW0005304 | Transit Delay - Technical issue, 2 day delay | Transit Delay - Technical issue, 2 day delay | | ESW0005305 | Transit Delay - Weather related issue, 1 day delay | Transit Delay - Weather related issue, 1 day delay | | ESW0005306 | Transit Delay - Weather related issue, 2 day delay | Transit Delay - Weather related issue, 2 day delay | | ESW0005307 | Transit Delay - Capacity issue, 1 day delay | Transit Delay - Capacity issue, 1 day delay | | ESW0005308 | Transit Delay - Capacity issue, 2 day delay | Transit Delay - Capacity issue, 2 day delay | | ESW0005309 | Transit Delay - Ground transport delay | Transit Delay - Ground transport delay | | ESW0005310 | Transit Delay - ESW Data Issue | Transit Delay - ESW Data Issue | | ESW0005311 | MITI – Retailer Data Issue | MITI – Retailer Data Issue | | ESW0005401 | Transit Delay - Confiscated by Customs | Transit Delay - Confiscated by Customs | | ESW0005402 | Transit Delay - Awaiting Customs clearance | Transit Delay - Awaiting Customs clearance | | ESW0005403 | Transit Delay - Customs checks | Transit Delay - Customs checks | | ESW0005404 | Transit Delay - Customs enquiry | Transit Delay - Customs enquiry | | ESW0005405 | Transit Delay - Shopper to supply information | Transit Delay - Shopper to supply information | | ESW0005406 | Transit Delay - Commercial Invoice required | Transit Delay - Commercial Invoice required | | ESW0005407 | Transit Delay - D\&T not paid | Transit Delay - D\&T not paid | | ESW0005408 | Transit Delay - Cannot contact shopper | Transit Delay - Cannot contact shopper | | ESW0005409 | Transit Delay - Pending Shopper ID | Transit Delay - Pending Shopper ID | | ESW0005410 | Transit Delay - Customs delay, expect 1 day delay | Transit Delay - Customs delay, expect 1 day delay | | ESW0005411 | Transit Delay - Customs delay, expect 2 day delay | Transit Delay - Customs delay, expect 2 day delay | | ESW0005412 | Transit Delay - Missing data for processing | Transit Delay - Missing data for processing | | ESW0005413 | Transit Delay - Formal Clearance required | Transit Delay - Formal Clearance required | | ESW0005414 | Transit Delay - Customs processing delay, Flight delay impact | Customs processing delay, Flight delay impact | | ESW0005415 | Transit Delay - Customs processing delay, COVID19 related delay | Customs processing delay, COVID19 related Delay | | ESW0005416 | Transit Delay - Customs processing delay, COVID19 related delay | Customs processing delay, COVID19 related Delay | | ESW0005417 | Transit Delay - Not injected in last mile | Transit Delay - Not injected in last mile | | ESW0005418 | LM Update - Customs Clearance confirmed | LM Update - Customs Clearance confirmed | | ESW0005419 | LM Update - Injected to network confirmed | LM Update - Injected to network confirmed | | ESW0005501 | Transit delay - Under investigation, delayed | Transit delay - Under investigation, delayed | | ESW0005502 | Transit delay - Under investigation, transit delay | Transit delay - Under investigation, transit delay | | ESW0005503 | Mistroute - Package misrouted, under investigation | Mistroute - Package misrouted, under investigation | | ESW0005504 | With Third-Party | With Third-Party | | ESW0005505 | Transit delay - Carrier Investigation ongoing | Transit delay - Carrier Investigation ongoing | | ESW0005506 | Delivered - NO POD or Third Party | Delivered - NO POD or Third Party | | ESW0005507 | Attempted Delivery | Attempted Delivery | | ESW0005508 | With Delivery Partner for delivery | With Delivery Partner for delivery | | ESW0005509 | In Transit - Data issue | In Transit - Data issue | | ESW0005510 | Transit Delay - flight-related, expect 1 day delay | Transit Delay - flight-related, expect 1 day delay | | ESW0005511 | Transit Delay - flight-related, expect 2 day delay | Transit Delay - flight-related, expect 2 day delay | | ESW0005512 | With Delivery Partner for delivery | With Delivery Partner for delivery | | ESW0005513 | Transit Issue - Manifested but not received | Transit Issue - Manifested but not received | | ESW0005514 | Transit Delay - flight delay impacting delivery | Transit Delay - flight delay impacting delivery | | ESW0005515 | Transit delay - Under investigation | Transit delay - Under investigation | | ESW0005516 | CTS General Update | CTS General Update | | ESW0005517 | Lost Package - Under investigation | Lost Package - Under investigation | | ESW0005518 | Lost Package - Claim process opened with Carrier | Lost Package - Claim process opened with Carrier | | ESW0005519 | MITI Final mile address issue | Final mile address issue | | ESW0005520 | Package at risk | Final Mile Package at risk | | ESW0005521 | MITI Last Mile - Major weather disruption | Final Mile - Major weather disruption | | ESW0005522 | MIT Last Mile - Uncontrollable Delay | Final Mile - Uncontrollable Delay | | ESW0005523 | MITI Flight Delay - Covid19 Related | Flight Delay - Covid19 Related | | ESW0005524 | MITI Pending COD payment | MITI Pending COD payment | | ESW0005525 | Package Undeliverable - Returns Initiated | Package Undeliverable - Returns Initiated | | ESW0005X01 | General transit delay, delivery delay unknown | General transit delay, delivery delay unknown | | ESW0005X02 | Transit Delay Email - up to 3 day delay | Transit Delay Email - up to 3 day delay | | ESW0005X03 | Transit Delay Email - up to 5 day delay | Transit Delay Email - up to 5 day delay | | ESW0005X04 | Transit Delay Email - up to 8 day delay | Transit Delay Email - up to 8 day delay | | ESW0005X05 | Transit Delay Email - up to 10 day delay | Transit Delay Email - up to 10 day delay | | ESW0008000 | ESW CS Service Now Ticket Received- Enquiry Lodged | ESW CS Service Now Ticket Received- Enquiry Lodged |

# Light Touch Integration Connect your storefront to ESW services with minimal implementation effort. {% hint style="success" icon="memo-circle-info" %} ## Technical Details See [Light Touch Integration](/light-touch-integration) (LTI) documentation for technical details. {% endhint %} ESW Light Touch Integration (LTI) connects your storefront to ESW services with minimal effort. It reduces the work required for flows such as PreOrder and Order Confirmation webhooks. {% hint style="info" icon="store" %} ESW Light Touch Integration supports different features by platform. All supported platforms include **Country Selector**, **Dynamic Pricing**, and **Returns Integration**. {% endhint %} BigCommerce, WooCommerce, and Commerce Tools support checkout and order status synchronization. Web Platform supports fixed pricing. Callback API supports every feature, including fixed pricing, checkout, and order status synchronization. Use the feature pages below for implementation details.

	Country Selector	Dynamic Pricing	Fixed Pricing	Checkout	Returns Integration	Order Status Sync
BigCommerce
WooCommerce
Commerce Tools
Web Platform
Custom (Callback API)

# Embedded Checkout Keep shoppers on your storefront with ESW iFrame Checkout and Light Touch Integration features for localization, payments, and consent. Embedded Checkout allows shoppers to complete their purchases directly within your storefront using an iFrame provided by ESW. This feature enhances the shopping experience by keeping the entire checkout process on the retailer’s site, thereby increasing shopper trust and confidence. Light Touch Integration (LTI) is a simple way to connect an eCommerce storefront with ESW using a JavaScript widget. It is easy to set up with scripts and helps create a smooth shopping experience for customers.

	Cover image	Cover image (dark)	Cover image (dark)	Cover image (dark)	Cover image (dark)	Cover image (dark)
Country & Currency Selector Adjusts store settings based on the shopper’s location and currency.	/files/NZ6ut502fUclyC5umZeT	/files/urNjaLur0ul6jH0dyWhf	/files/rl81lIU4IzM94CVbDwLL	/files/rl81lIU4IzM94CVbDwLL	/files/rl81lIU4IzM94CVbDwLL	/files/rl81lIU4IzM94CVbDwLL
Pricing Conversion Displays accurate prices in the shopper’s local currency.	/files/s4SN62Qd7QzuPUZlSksG	/files/BUxHyHPvrPzE5f5e6viI		/files/9Ix0swCu3Fw7cnE4VXxN	/files/9Ix0swCu3Fw7cnE4VXxN	/files/9Ix0swCu3Fw7cnE4VXxN
ESW iFrame Checkout Lets shoppers check out directly on the storefront without redirection.	/files/XCzeUsZZ5xMCqiOK8gzc	/files/jfF0496z0rzXBJidjZ0b				/files/3MBubEJJZmNSZKxvVECM
Express Payments Supports payment methods such as PayPal, Apple Pay, and Google Pay.	/files/gMYsvBEHgaaDHKZgKM4r	/files/pS0TSpsO2gxd3b4Q0X7Q				/files/kjbJbJR7abG5u3N5s4SG
Cookie Consent Manages shopper consent for cookies to support privacy compliance.	/files/M5wiaw4wIMU3xS9ksqkA	/files/RgGGoBpG8B8wKOVeoPFM				/files/TfyiylYsmQ3yg88FFAfY

When used with the Magento plugin, LTI makes it easier for anyone with custom frontends to integrate Magento as a backend. This combination provides a simple and efficient solution for creating a seamless shopping experience. #### Technical Details The integration of Magento with LTI provides flexibility, supporting various levels of implementation based on specific requirements: * Full Frontend Integration: Incorporates complete features such as pricing conversion, delivering a seamless and localized shopping experience for customers. * Partial Integration: Enables the addition of specific functionalities, such as the ESW checkout process using an iFrame, without altering the entire frontend. This flexibility allows you to select the necessary components and customize the integration to align with business requirements. # Direct Integration Embed ESW Checkout in a dedicated storefront iframe using event-based communication, PreOrder URLs, and domain masking. * The retailer needs to embed an iframe on a dedicated page (e.g., /checkout). This iframe will host the checkout experience. * Script Injection: A script must be injected into the \ section of the retailer’s page. This script, hosted on a CDN, facilitates communication between the retailer’s site and the checkout iframe. ### Event-based Communication * The script listens for events like iframe-ready and iframe-height-update, ensuring dynamic height adjustments. * The retailer needs to handle build-checkout and begin-checkout events to fetch and assign the checkout URL to the iframe. * Pre-order URL Handling: Before rendering the iframe, the retailer must generate a pre-order URL by calling the checkout API and then pass this URL via an event. ### Domain Masking Requirement {% hint style="info" icon="globe-pointer" %} See [Domain Masking Configuration](/checkout-api/checkout-api/domain-masking) {% endhint %} * The iframe must have the same domain as the retailer’s site to meet security and compliance standards. * X-Frame options and security headers need to be configured to prevent clickjacking. * A domain masking solution using TLS and CDN certificates ensures seamless integration. * Generic Public Script: A script hosted on the retailer’s CDN will be available for all tenants. This script simplifies the integration process by automatically handling iframe rendering and event communication. *** ### Steps #### 1. Set Up the Dedicated Checkout Page * The checkout should be a separate page (e.g., /checkout). * The entire page should be occupied by the checkout iframe. #### 2. Inject the Required Script * The CDN-hosted script is responsible for rendering the checkout iframe. * Include the script in the \ of the checkout page. #### 3. Generate the Pre-Order URL Before the checkout iframe is rendered, the retailer must: 1. Call the checkout API to generate a pre-order URL. 2. Send a "build checkout" event with the URL. #### 4. Render the Checkout Iframe Once the pre-order URL is obtained, trigger the event to embed the iframe. #### 5. Handle Events for Iframe Communication The embedded checkout script sends events to the retailer’s page. ### Events to Handle: * build-checkout: an event that needs to be emitted from the retailer's storefront to bootstrap checkout embedding. This event requires the checkout URL to be sent and set as iframe data. * iframe-ready : an event emitted by the script once the iframe is loaded. It notifies child iframes about the storefront’s origin, which should be used for secure communication. * esw-navigate-outside: an event emitted by the checkout in case external navigation needs to be done. Contains an external URL that the storefront should navigate to. * Other communication events, from checkout itself or payment panel as an inner iframe, are captured and proxied by script back to their consumers as contentWindow so it keeps the existing communication mechanism. * esw-update-iframe-height: an event to notify the size of the iframe height to avoid the use of scroll bars. * esw-scroll-to-error: an event to notify the origin that the view should be scrolled. It triggers once the checkout form contains invalid controls. It accepts ScrollToOptions that defines top and left dimensions. ### iFrame Communication Script * The iframe sends events (iframe-ready, esw-update-iframe-height, navigate-outside) to the parent page. * The parent page listens and responds (e.g., adjusting iframe height, redirecting users). * The iframe-communication.js script ensures seamless interaction. `` indicates that a separate script handles communication between the iframe and the parent page. ### Security & Domain Masking Setup #### Why This Matters * The iframe must have the same domain as the parent page (or use domain masking). * Proper security headers protect against clickjacking and unauthorized embedding. ### Steps for Domain Masking {% hint style="success" icon="globe-pointer" %} For more information, refer to [Domain Masking Configuration](/checkout-api/checkout-api/domain-masking) {% endhint %} 1. Obtain a TLS Certificate for checkout.retailer.com. 2. Configure a CNAME Record e.g., checkout.retailer.com → checkout-service.provider.net 3. Ensure API endpoints match the retailer’s domain: {% hint style="info" %} e.g., `https://checkout.retailer.com/api/checkout` {% endhint %} 4. Update security headers # iFrame Integration {% hint style="danger" %} #### Managed Process Integration is implemented by ESW. {% endhint %} {% tabs %} {% tab title="Tutorial" %} {% embed url="" fullWidth="false" %} {% endtab %} {% endtabs %} # Coming Soon

# Model Context Protocol (MCP) Connect AI clients to the ESW MCP server, configure OAuth or service tokens, and use approved ESW knowledge tools. The ESW Model Context Protocol server provides retrieval tools against the sanctioned ESW documentation corpus, allowing assistants to ground their responses in approved material ## Connect to the ESW MCP ### Cursor Install in Cursor Open Cursor and click install. Alternatively, add the following to your `~/.cursor/mcp.json` file. {% embed url="" %} Refer to Cursor docs for more info {% endembed %} {% code expandable="true" %} ```json { "mcpServers": {"esw": { "url": "https://mcp.esw.com/mcp" } } } ``` {% endcode %} ### VS Code Install in VS Code Open VS Code and click Install. Alternatively, add the following to your `.vscode/mcp.json` file in your workspace. Refer to [VS Code docs](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more information. {% code expandable="true" %} ```json { "servers": {"esw": { "type": "http", "url": "https://mcp.esw.com/mcp" } } } ``` {% endcode %} ### Claude Code To add MCP to Claude Code, run the following command. {% code expandable="true" %} ```bash claude mcp add --transport http esw https://mcp.esw.com/mcp ``` {% endcode %} {% embed url="" %} Refer to Claude Code docs for more info {% endembed %} ### ChatGPT You can enable MCP servers on ChatGPT if you have a Pro, Plus, Business, Enterprise, or Education account. Follow the [OpenAI documentation](https://platform.openai.com/docs/guides/developer-mode) for instructions. Use the following parameters when setting up your custom connector: * The server URL is `https://mcp.esw.com/mcp`. * Use `OAuth` as the connection mechanism. The ESW MCP server also works with OpenAI’s Responses API when building autonomous agents or calling tools through custom runtimes. {% embed url="" %} ### Other MCP is an open protocol supported by many clients. Consult your client’s documentation for connection guidance. Use the server URL `https://mcp.esw.com/mcp` and OAuth whenever possible. If your client cannot perform OAuth, request a service API key from the ESW MCP team and pass it in the `Authorization` header as a bearer token: {% code expandable="true" %} ```json "esw": { "url": "https://mcp.esw.com/mcp", "headers": { "Authorization": "Bearer <>" } } ``` {% endcode %} *** ## OAuth The ESW MCP server supports OAuth 2.1 with PKCE, optional Dynamic Client Registration, and API key authentication for service accounts. Most clients use the authorization code + PKCE grant to request scopes, while automated systems can register dynamically at `https://mcp.esw.com/register` or supply an administrator-issued API key. Choose OAuth for human-driven sessions, Dynamic Client Registration for self-service client onboarding, and API keys for tightly scoped automation. ## Autonomous Agents If you’re building agentic software or integrating with orchestration frameworks, you can pass a service token or restricted API key as a bearer token to the MCP server. {% code expandable="true" %} ```json curl https://mcp.esw.com/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <>" \ -d '{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "kb_search", "arguments": {"query": "reset VPN token", "top_k": 3} }, "id": 1 }' ``` {% endcode %} ## Tools The server exposes the following [MCP tools](https://modelcontextprotocol.io/docs/concepts/tools). Enable operator confirmation inside your MCP client, and be cautious when chaining this server with others to avoid prompt-injection attacks. To request additional tools, email | Resource | Tool | Data source / API | | ------------------ | ---------- | ---------------------------------------- | | ESW Knowledge Base | kb\_search | Internal ESW knowledge base search index | Each tool returns a structured payload containing the normalized query, result count, and an array of documents with page titles, URLs, content snippets, and relevance scores. *** {% embed url="" %} Contact the [ESW MCP team](mailto:ai-support@esw.com) # Microsoft Copilot Integration Guide Set up agent-led commerce, manage catalogs, and resolve common issues. Use this guide to enable agentic commerce through ESW. Shoppers can buy directly in AI experiences such as Microsoft Copilot, Google Gemini, and Shopify-powered storefronts. ESW enables your products to appear where shoppers already ask for help: AI agents such as Microsoft Copilot and Google Gemini. You deliver product discovery, checkout, and order completion through ESW checkout services, so shoppers can move from intent to purchase with fewer steps. Contact your ESW CSM to enable ESW Agentic Commerce for your brand. UCP gives AI platforms a clear, standard way to work with your commerce services. Use it to let agents: * Discover your products in Microsoft and Google shopping surfaces * Retrieve accurate product details, price, and availability * Create checkout sessions through ESW * Complete purchases and return clear order outcomes {% hint style="info" %} ESW supports the `Jan 23, 2026 UCP specification` and uses this guide to anchor your implementation with more versions coming soon. {% endhint %} # UCP profile setup Configure the UCP profile for agent-led ESW checkout. Enable your UCP profile so Microsoft Copilot, Google Gemini, and Shopify assistants can find products. Agents route qualified shoppers into ESW checkout. ESW pushes catalog changes to Microsoft Merchant Center. This avoids relying on site crawling for accurate discovery results. Microsoft Merchant Center creates searchable indexes from your product data. Agents check relevance, price, and availability before creating checkout sessions. ### Host the UCP profile Your UCP profile is also called the UCP well-known file. Host the manifest JSON on your domain. It tells agents which commerce actions your brand supports. It also connects agents to the ESW checkout API. The January 23, 2026 UCP specification supports these checkout session actions: * Create * Update * Retrieve and cancel ESW completes the order and returns the order number and status. The standard post-purchase journey continues through confirmation emails, fulfilment, customer service, tracking, and returns. ### Example UCP well-known file {% code expandable="true" %} ```json { "ucp": { "version": "2026-01-23", "services": { "dev.ucp.shopping": [ { "version": "2026-01-23", "spec": "https://ucp.dev/specification/overview", "transport": "rest", "endpoint": "https://checkout-acp-api.test.eshopworld.net/UCP/QAUQAU", "schema": "https://ucp.dev/2026-01-23/services/shopping/openapi.json" } ] }, "capabilities": { "dev.ucp.shopping.checkout": [ { "version": "2026-01-23", "spec": "https://ucp.dev/specification/checkout", "schema": "https://ucp.dev/2026-01-23/schemas/shopping/checkout.json", "extends": null, "config": null } ], "dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "spec": "https://ucp.dev/specification/fulfillment", "schema": "https://ucp.dev/2026-01-23/schemas/shopping/fulfillment.json", "extends": "dev.ucp.shopping.checkout", "config": null } ] }, "payment_handlers": { "com.adyen": [ { "id": "adyen-card-tokenization", "version": "2026-01-23", "spec": "https://ucp.dev/specification/payment-handler-guide", "config_schema": "https://ucp.dev/2026-01-23/handlers/tokenization/openapi.json", "instrument_schemas": [ "https://ucp.dev/2026-01-23/handlers/tokenization/schemas/card_instrument.json" ], "config": { "environment": "test", "public_merchant_id": "e8b29c2e-dd09-48f3-949e-f63fbb416041" } } ] } }, "signing_keys": [ { "kid": "ucpgo_2025", "kty": "EC", "crv": "P-256", "x": "WbbXwVYGdJoP4Xm3qCkGvBRcRvKtEfXDbWvPzpPS8LA", "y": "sP4jHHxYqC89HBo8TjrtVOAGHfJDflYxw7MFMxuFMPY", "use": "sig", "alg": "ES256" } ] } ``` {% endcode %} # Merchant Center and catalog preparation Prepare catalog data for AI shopping discovery. ### Microsoft Merchant Center access For brands without a Microsoft Merchant Center account, ESW operates the account and creates the store. ESW sends enriched product data to Microsoft Copilot shopping discovery in the United States. Support for existing Microsoft Merchant Center accounts is planned. Google Merchant Center support is also planned. Prepare your catalog now for both surfaces. ### Provide the product catalog Provide one CSV catalog so ESW can prepare products for agent-led discovery and checkout. Include every required field. Add recommended fields where available: * Selling points and key features * Category, material, and intended use * Product attributes that explain buyer suitability ### Ingestion and enrichment ESW enriches your catalog for AI agents. Clear selling points and features help agents understand product value. ESW combines these fields with product titles, categories, intended use, materials, and intended users. The resulting descriptions help agents recommend appropriate products. Describe the shopper need clearly. For example, state whether a product suits running, travel, gaming, office work, or children. ### Enhanced data distribution ESW sends enriched catalogs to the relevant merchant center, starting with Microsoft Merchant Center. Provide one catalog per market. Each catalog should contain the correct language, pricing, availability, and selling points. Multi-market discovery across ESW-operated markets is planned for `Q4 2026`. You can apply unique selling points and key features to each market file. # Manage catalog uploads (SFTP) Upload and maintain market-specific product catalogs through SFTP. Send catalog files to ESW through SFTP. Use one file per market whenever prices or availability change. ### Upload cadence * Send an initial full catalog with every active, in-stock product. * Upload a new file for price, availability, or attribute changes. * Upload a full catalog at least monthly. Set `availability` to `out_of_stock` to remove a product. A file can contain new products, updates, and removals. Allow up to 72 hours after the first successful upload for Microsoft validation. ESW monitors validation and resolves blockers to product visibility. ### SFTP location Upload files to: ```hurl https://eshopworld3.files.com/files/Development/Core/Retailers/RetailersFTP//ProductFeed/Pending ``` * `` is your agreed brand code. * `` is the target environment, such as `TEST` or `PROD`. Example: ```hurl https://eshopworld3.files.com/files/Development/Core/Retailers/PGLRetailersFTP/TEST/ProductFeed/Pending ``` ### File naming Use this filename format: ```csv {catalogFileName}-{countryIso3166Alpha2}.csv ``` ### Preserve product IDs in Excel Excel can convert long values into scientific notation. This can corrupt GTINs, product IDs, and MPNs. 1. Format every ID column as **Text** before entering values. 2. Import CSV files with **Data → From Text/CSV**. 3. Set the GTIN column type to **Text** before loading. Before upload, confirm that each ID is complete. For example, use `5063589815347`, not `1.24504323E+12`. Open the CSV as a `.txt` file in Notepad to verify IDs. Reformatting a converted Excel cell does not restore its original value. Correct the source data and export again. # Product catalog specification Field requirements for product catalog CSV files. Use this specification when preparing catalog files. {% file src="/files/QVnFPRNw0s9iePaHdqJv" %} ### Core fields | Field | Requirement | Description and example | | -------------------- | ----------- | ---------------------------------------------------------------------------------------------------------- | | `productId` | Required | Unique retailer product ID or SKU. Maximum 50 characters. Example: `SKU-12345`. | | `marketCountryIso` | Optional | Two-letter ISO 3166-1 market code. Required on every row for multi-country files. Example: `GB`. | | `title` | Required | Product title. Example: `Men’s Cotton Oxford Shirt`. | | `brand` | Optional | Manufacturer, brand, or publisher. Maximum 70 characters and 10 words. Defaults to retailer brand. | | `mpn` | Optional | Manufacturer Part Number. Up to 70 alphanumeric characters. | | `gtin` | Recommended | Barcode, GTIN, UPC, EAN, or ISBN. Numeric, up to 14 digits per value. Separate up to 10 values with pipes. | | `description` | Required | No HTML or promotional text. Maximum 10,000 characters. Include size, colour, and pattern where relevant. | | `material` | Optional | Material composition. Required unless the item is a digital good. Example: `100% Cotton`. | | `countryOfOriginIso` | Required | Two-letter ISO 3166-1 manufacturing country code. | | `availability` | Required | One of: `preorder`, `out_of_stock`, `in_stock`, or `backorder`. | | `condition` | Optional | One of: `new`, `refurbished`, or `used`. | | `contentLanguageISO` | Optional | Two-letter ISO 639-1 product language code. Example: `en`. | ### Price, weight, and links | Field | Requirement | Description and example | | ---------------------- | ----------- | ----------------------------------------------------------- | | `price` | Required | Decimal price with a full-stop separator. Example: `29.99`. | | `currencyIso` | Required | ISO 4217 currency code. Example: `GBP`. | | `weight` | Optional | Decimal product weight. Example: `0.35`. | | `weightUnit` | Optional | One of: `lb`, `oz`, `g`, or `kg`. | | `link` | Required | Direct product page URL. | | `imageLink` | Required | Main product image URL. | | `additionalImageLinks` | Optional | Up to 10 extra image URLs, separated by commas. | ### Product attributes | Field | Requirement | Description and example | | ------------- | ----------- | ---------------------------------------------------------------------------------------- | | `color` | Conditional | Up to three values separated by `/`, dominant first. Required for Apparel & Accessories. | | `size` | Optional | Product size. Maximum 100 characters. | | `gender` | Optional | One of: `male`, `female`, or `unisex`. | | `category` | Optional | Category path using `>` only. Maximum 255 characters. | | `productType` | Optional | Full category path. Maximum 750 characters. | | `pattern` | Optional | Pattern or graphic print. Maximum 100 characters. | | `keywords` | Recommended | Highlights and USPs. Maximum 150 characters. Separate values with commas. | | `ageGroup` | Conditional | `newborn`, `infant`, `toddler`, `kids`, or `adult`. Required for Apparel. | | `itemGroupId` | Optional | Shared ID for variants. Up to 50 alphanumeric characters. | | `sizeType` | Optional | Apparel modifier. Example: `petite`. | | `sizeSystem` | Optional | Apparel modifier. Example: `UK`. | ### Promotions and bundles | Field | Requirement | Description and example | | ------------------------ | ----------- | -------------------------------------------------------------- | | `salePrice` | Optional | Discounted item price. Example: `21.99`. | | `salePriceEffectiveDate` | Optional | Sale time range. Example: `2026-06-25T00:00/2026-06-30T23:59`. | | `costOfGoodsSold` | Optional | Merchant’s actual item cost. Example: `15.00`. | | `promotionId` | Optional | Promotion identifier. Example: `SUMMER_SALE`. | | `isBundle` | Conditional | Merchant-defined bundle flag: `yes` or `no`. | | `multipack` | Conditional | Number of identical grouped items. Example: `3`. | | `adult` | Conditional | Adult-oriented content flag: `yes` or `no`. | ### Enrichment and shopper information | Field | Requirement | Description and example | | ------------------------ | ----------- | ------------------------------------------------------------------------------------------------------ | | `productHighlight` | Optional | Product highlights, separated by commas. | | `productDetail` | Optional | Product details using structured key-value information. | | `returnExceptionPolicy` | Optional | Product-specific return exception. Maximum 50 characters. This information may appear during checkout. | | `consumerMessageType` | Optional | Warning category, such as `legal_disclaimer`, `safety_warning`, or `prop_65`. | | `consumerMessageContent` | Optional | Shopper warning text. Maximum 1,000 characters. Supports ``, `
`, ``, and ``. | | `documentLinks` | Optional | Related manual, assembly, or safety document links. Separate values with commas. | | `relatedProducts` | Optional | Related products and their relationship identifiers. Separate values with commas. | ### GTIN formats Use numeric GTIN values only. Supported formats include: * **UPC / GTIN-12 / UPC-A** — 12 digits, mainly North America. * **EAN / GTIN-13** — usually 13 digits, also 8 or 14 digits. * **JAN / GTIN-13** — 8 or 13 digits, used in Japan. * **ISBN** — 10 or 13 digits for books. ISBN-13 usually starts with `978` or `979`. # Checkout, testing, and errors Understand payment handling, validation, and shopper error recovery. ### Payment handling ESW handles Adyen payments through a secure token-based flow. Adyen provides the payment token. ESW maps the token to the shopper conversation, authorizes payment, and returns the checkout outcome. ### Validation and testing ESW validates the checkout services against the manifest. Testing confirms UCP actions perform efficiently and product data synchronizes correctly to merchant centers. ### Checkout service errors ESW separates shopper-correctable issues from ESW-managed issues. Shoppers receive guidance for correctable details. ESW resolves catalog, authentication, capacity, and infrastructure issues behind the scenes. | Scenario | Who handles it | Shopper experience | | ----------------------------------------- | --------------------------------- | --------------------------------------------------------------- | | Invalid personal details | Shopper, prompted by the AI agent | Correct and resubmit details. | | Unsupported delivery country | Shopper, prompted by the AI agent | Choose a supported country. | | Product catalog or pricing data issue | ESW | Hidden from the shopper. ESW resolves it. | | Authentication or permissions failure | ESW | ESW adapter handles it. No action required. | | Rate limiting or temporary capacity issue | ESW | Automatic retry after a short delay. | | Infrastructure or integration failure | ESW | A graceful message appears. ESW resolves it. | | Minor data formatting issue | ESW | ESW silently corrects it where possible. | | Payment declined | ESW | A graceful message reflects the failure reason. | | 3DS or fraud challenge required | Shopper and ESW | Complete the challenge, then resume the same checkout session. | | Unsupported payment method | Shopper, prompted by the AI agent | Choose a supported method for the market. | | Item out of stock at checkout | Shopper and ESW | Remove the item or choose an alternative. ESW refreshes totals. | | Address validation failure | Shopper, prompted by the AI agent | Correct the specified field before retrying. | # Catalog FAQs Resolve common catalog upload and product discovery questions. ### Uploading catalogs

Where do I upload my catalog?
Upload to your assigned tenant folder through SFTP. Use the exact brand code, environment, and `ProductFeed/Pending` path provided by ESW. Confirm the folder with your ESW Customer Success Manager if needed.

Can I upload multiple files for one market?
No. Send one CSV per market. Include every product for that market. Do not split files by category, brand, or action type.

What belongs in my first upload?
Include every active, in-stock product you want discoverable in Microsoft Copilot. Include required fields and useful selling points, features, category, material, and intended use.

What format do I need?
Send a UTF-8 CSV. Populate mandatory fields for each product category. Validate the file before upload.
### Timing and markets

When do products appear in Microsoft Merchant Center and Copilot?
Allow up to 72 hours after successful upload. Upload at least four days before launches, campaigns, or price changes.

Which markets support Microsoft Copilot purchases?
Microsoft Copilot purchasing currently supports the United States. Prioritize accurate US catalogs, then prepare market-specific files for future expansion.

When should I upload sale prices?
Upload changes at least 72 hours before launch. Upload major event changes at least four days ahead. Verify results before peak traffic.

How often should I update catalogs?
Send a full catalog at least monthly. Upload price, availability, and removal changes as soon as they occur.
### Errors and corrections

Why was my entire file rejected?
A structural error prevented parsing. Export a fresh UTF-8 CSV. Confirm equal column counts, escaped commas and quotes, then re-upload.

Can some products succeed while others fail?
Yes, if the file structure is valid. ESW uploads valid products and logs failed products. Correct failed SKUs and re-upload them.

Why did products fail with a non-USD pricing error?
Microsoft Copilot purchasing currently requires USD. Convert prices to USD, remove currency symbols, use values like `49.99`, then re-upload.

How do I update or remove products?
Use the same SKU or product ID and upload the latest values. To remove a product, set `availability` to `out_of_stock`. Omitting a SKU does not remove it.

Why are IDs displayed as scientific notation?
Excel converted long IDs and corrupted them. Regenerate the CSV from the source system. Import with **Data → From Text/CSV** and set ID columns to **Text**.

How do I verify data before uploading?
Open the CSV in Notepad. Confirm long IDs appear in full, such as `5063589815347`, not `1.23E+13`. Regenerate the file if values are converted.

What does an empty catalog file error mean?
The CSV has no product rows. Re-run the export. Confirm it has headers and product data, then upload it again.

Why are products missing mandatory fields?
Each category requires specific fields. Use the catalog specification, populate required fields, and re-upload corrected products.
# Shopify Native ESW integration leverages Shopify's native checkout to handle shopper's purchase flow.

Install Apps Configuration Integration Workflow

Integration matrix
| | ESW | Shopify | | :---------------------------------: | :-------------------------------------------------------------: | :-------------------------------------------------------------: | | Browsing | | | | Checkout Flow | | | | Customer Communications | | | | Gift Cards, Coupons & Promotions | | | | Checkout Languages and Translations | | | | Price Calculation | | | | Shipping Methods & Pricing | | | | Duty & Tax Calculation | | | | Payment Methods | | | | Merchant of Record | | | | Product Restrictions | | | | Returns & Tracking Translations | | | {% hint style="info" icon="shopify" %} Shopify owns the checkout flow {% endhint %}
# Quick Start Guide Install and configure the ESW Shopify apps, coordinate ESW onboarding provisioning, and prepare for testing and go-live. Welcome to ESW! Expand your Shopify store globally with ESW. From multi-currency payments to duties, taxes, and international shipping, ESW simplifies global commerce so you can sell anywhere - all while staying compliant, all from one platform. Important note: to use the ESW Shopify integration, you must download and enable both International and Payment Apps. They are designed to work together and cannot be used separately. Once you have downloaded these two apps, please contact the ESW Onboarding team. They will complete the provisioning for your account, so the apps can be activated and ready to use. Let’s get started. {% hint style="danger" icon="light-emergency-on" %} #### Before you Begin * The integration of the ESW Shopify Apps requires that you install, enable, and configure *both*, the International App and the Payments App for the solution to be functional. * Note that these applications are interdependent. * These Apps cannot be implemented or used separately. {% endhint %}
### Managed Process * After the apps are installed, your account must be provisioned by the ESW Onboarding Team. * Contact our team and provide your shop domain to notify them of your installation. The onboarding team will complete the provisioning for you. * Once provisioning is complete, the app will become available for activation in your Shopify admin. * Activation is the final, simple step that enables ESW apps. #### Order of Action {% stepper %} {% step %} ### Install the International App Install the ESW Shopify [International App](/shopify/shopify-native/quick-start-guide/install-esw-shopify-apps#international-app-1). {% endstep %} {% step %} ### Install the Payments App Install the ESW Shopify [Payments App](/shopify/shopify-native/quick-start-guide/install-esw-shopify-apps#payments-app-1). {% endstep %} {% step %} ### Create a Market [Create and configure a m**a**rket](/shopify/shopify-native/configuration/create-a-new-market) for your target region(s). {% endstep %} {% step %} ### Add Legal Messaging Add the [ESW Privacy Notice](/shopify/shopify-native/configuration/add-legal-messaging) to your Shopify checkout page. {% endstep %} {% step %} ### Testing Period {% hint style="info" icon="flask-vial" %} Conduct testing to validate: * App integrations * Payment workflows * Market settings and configurations {% endhint %} {% endstep %} {% step %} ### Go-Live Once testing is successful, proceed with **go-live** on the agreed date. {% hint style="warning" icon="rectangle-beta" %} Testing before go-live ensures smooth functionality and reduces potential issues in production. {% endhint %} {% 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 U as User participant SA as Shopify Admin participant TP as Testing Period participant GL as Go-Live Note over U,SA: Shopify setup U->>SA: Install the International App U->>SA: Install the Payments App U->>SA: Add a Market Note over SA,TP: Validation phase SA->>TP: Conduct testing to validate functionality Note over TP,GL: Launch phase TP->>GL: Proceed with go-live on agreed date ``` {% endcode %} {% endstep %} {% endstepper %} *** # Install ESW Shopify Apps Install ESW Shopify apps {% hint style="danger" icon="light-emergency-on" %} * Install, enable, and configure the ESW International App and Payments App. * If you offer alternative payment methods (APMs), also install the relevant ESW APM app. * If you use ESW Returns & Exchanges, also install the ESW [Returns & Exchanges app](/shopify/shopify-native/quick-start-guide/install-returns-and-exchanges-app). {% endhint %} Install the International App and Payments App. Also install an ESW APM app when offering APMs. Install the ESW Returns & Exchanges app when using ESW Returns & Exchanges. {% tabs %} {% tab title="Installation" %}
Cover image
International App /files/oTlyQVDlzuHglHcU6nBW /pages/3b245df82504f55e59cbf60afbcca675dbd0dbed#international-app
Payment App /files/nY5CiTGIRHxwZy1SjpvA /pages/3b245df82504f55e59cbf60afbcca675dbd0dbed#payments-app
Returns & Exchanges App /files/CS8AcGx9WAOR5GLEyuip /pages/7791b749e2bbaa60bbc865dfde5395df56ce4680
{% endtab %} {% endtabs %}
International App

The International App empowers merchants to expand internationally by localizing pricing, managing orders, and handling logistics from the Shopify store to ESW-supported markets – a streamlined experience to help you and your business. Using the International App offers: * Seamless Global Reach: Calculates international prices with duties and taxes included, improving transparency for global shoppers, * Efficient Order Handling: Orders are taken directly into the ESW systems, streamlining fulfillment, * Simplified Logistics: ESW’s forward shipping service, reducing complexity for cross-border delivery, * Compliance Support: Duty and tax declarations for compliance. ### Installation {% stepper %} {% step %} ### Install link Click on the `Install Link` {% hint style="warning" icon="globe-pointer" %} Link to be provided by ESW {% endhint %} {% endstep %} {% step %} ### Install app Run the installation on the `myshopify` subdomain.
**Click** `Install` {% endstep %} {% step %} ### Contact ESW onboarding manager After the app is successfully installed, the following screen will appear.\ Please contact the Onboarding Manager to proceed with the configuration of your account, environment, and tenant for your brand.
{% endstep %} {% step %} ### Confirmation screen Once the tenant has been successfully configured, the following screen will appear within the app.\ You will be notified by ESW upon successful completion of the tenant configuration.
{% endstep %} {% step %} ### Update brand configuration settings Once the account, environment, and tenant have been set up, the brand configuration settings can be accessed and updated via the ESP link. Find the ESP link [here](https://esp.sandbox.eshopworld.com/brand-management/storefront-integration). {% endstep %} {% step %} ### View installation in your Shopify admin In your Shopify admin, click `Apps` to view the installed application.
{% endstep %} {% endstepper %} ***
Payments App
{% hint style="danger" icon="sliders-up" %} #### Works with * ESW International App * ESW Returns & Exchanges {% endhint %}
ESW offers a powerful global payment solution that makes every purchase feel local to your shoppers. The Payments App consolidates the most popular payment methods into one app and uses local acquiring to boost payment success and dynamic routing to show the most relevant options to each shopper. Using the Payments App offers: * Localized payment methods tailored to each market, * Processes payments locally to improve success rates, * Flexible business models including Merchant of Record, * Secure, compliant payment processing with fraud protection, * Optimized checkout displays the highest-converting payment options. ### Installation {% stepper %} {% step %} ### Install link
{% embed url="" %} {% endstep %} {% step %} ### Install app
**Click** `Install` at the bottom of the installation screen. {% endstep %} {% step %} ### Contact ESW onboarding manager Once the app is successfully installed, contact ESW onboarding manager to configure your account, environment, and tenant for your brand. {% endstep %} {% step %} ### Confirmation screen The app communicates readiness with Shopify. You will get a confirmation screen once the tenant has been successfully configured. {% endstep %} {% step %} ### Activate app
**Click** `Activate` {% endstep %} {% endstepper %} *** If these steps don’t work or you need further support, please contact [onboarding@esw.com.](mailto:onboarding@esw.com) # Install Returns and Exchanges App Install the ESW Returns and Exchanges app in Shopify, then contact ESW to provision and configure your tenant. {% @code-walkthrough/alert-block title="" message="Standalone App" type="success" %}
Returns and Exchanges App provides a localized, self-service returns experience for international shoppers through the ESW Returns Portal. * Improved Customer Experience: Shoppers can easily initiate returns through a branded, localized portal. * Return Logistics Simplified: ESW handles return routing and customs declarations, reducing operational overhead. * Duty & Tax Automation: Ensures accurate processing of return-related tax declarations, reducing compliance burdens. ## Installation Follow these steps to install the GRP Returns App: {% stepper %} {% step %} ### Install link Click the Shopify App Store link to install the ESW Returns and Exchanges app. {% hint style="info" %} Link to be provided by ESW. {% endhint %} {% endstep %} {% step %} ### Install app #### [Shopify Store](https://myshopify.com/) Run the installation on the `myshopify.com` subdomain.\ The installation screen will appear as shown below. Click Install app to proceed.
**Click** `Install` to proceed. {% endstep %} {% step %} ### Contact ESW onboarding manager Once the app is successfully installed, the following screen will appear.\ At this stage, please contact the Onboarding Manager to configure the account, environment, and tenant for your brand.
{% endstep %} {% step %} ### Confirmation screen Once the tenant has been successfully configured, the following screen will be displayed.\ You will be notified by ESW once the configuration is complete.
{% endstep %} {% step %} ### Update brand configuration settings Once account, environment and tenant have been setup, update brand configuration settings on ESP. Find the ESP link [here](https://esp.sandbox.eshopworld.com/brand-management/storefront-integration). {% endstep %} {% step %} ### View installation in your Shopify admin To view the installation, navigate to your Shopify admin and click `Apps`. {% endstep %} {% endstepper %} # Supported Countries Reference list of ESW-supported countries for Shopify, with ISO 3166-1 alpha-2 codes. ### A–J | Country | Code | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | | Albania | `AL` | | Algeria | `DZ` | | Andorra | `AD` | | Angola | `AO` | | Anguilla | `AI` | | Antigua and Barbuda | `AG` | | Argentina | `AR` | | Armenia | `AM` | | Aruba | `AW` | | Australia | `AU` | | Austria | `AT` | | Azerbaijan | `AZ` | | Bahamas | `BS` | | Bahrain | `BH` | | Bangladesh | `BD` | | Barbados | `BB` | | Belarus | `BY` | | Belgium | `BE` | | Belize | `BZ` | | Benin | `BJ` | | Bermuda | `BM` | | Bhutan | `BT` | | Bolivia | `BO` | | Bonaire, Sint Eustatius and Saba (Caribbean Netherlands) | `BQ` | | Bosnia and Herzegovina | `BA` | | Botswana | `BW` | | Brazil | `BR` | | Brunei | `BN` | | Bulgaria | `BG` | | Burkina Faso | `BF` | | Burundi | `BI` | | Cambodia | `KH` | | Cameroon | `CM` | | Canada | `CA` | | Cabo Verde | `CV` | | Cayman Islands | `KY` | | Central African Republic | `CF` | | Chad | `TD` | | Chile | `CL` | | China | `CN` | | Colombia | `CO` | | Comoros | `KM` | | Congo (Republic of the) | `CG` | | Congo (Democratic Republic of the) | `CD` | | Cook Islands | `CK` | | Costa Rica | `CR` | | Côte d’Ivoire | `CI` | | Croatia | `HR` | | Cuba | `CU` | | Curaçao | `CW` | | Cyprus | `CY` | | Czechia | `CZ` | | Denmark | `DK` | | Djibouti | `DJ` | | Dominica | `DM` | | Dominican Republic | `DO` | | Ecuador | `EC` | | Egypt | `EG` | | El Salvador | `SV` | | Equatorial Guinea | `GQ` | | Eritrea | `ER` | | Estonia | `EE` | | Ethiopia | `ET` | | Falkland Islands | `FK` | | Faroe Islands | `FO` | | Fiji | `FJ` | | Finland | `FI` | | France | `FR` | | French Guiana | `GF` | | French Polynesia | `PF` | | Gabon | `GA` | | Gambia | `GM` | | Georgia | `GE` | | Germany | `DE` | | Ghana | `GH` | | Gibraltar | `GI` | | Greece | `GR` | | Greenland | `GL` | | Grenada | `GD` | | Guadeloupe | `GP` | | Guatemala | `GT` | | Guernsey | `GG` | | Guinea | `GN` | | Guinea-Bissau | `GW` | | Guyana | `GY` | | Haiti | `HT` | | Holy See (Vatican City) | `VA` | | Honduras | `HN` | | Hong Kong | `HK` | | Hungary | `HU` | | Iceland | `IS` | | India | `IN` | | Indonesia | `ID` | | Iraq | `IQ` | | Ireland | `IE` | | Isle of Man | `IM` | | Israel | `IL` | | Italy | `IT` | | Jamaica | `JM` | | Japan | `JP` | | Jersey | `JE` | | Jordan | `JO` | ### K–T | Country | Code | | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- | | Kazakhstan | `KZ` | | Kenya | `KE` | | North Korea | `KP` | | South Korea | `KR` | | Kosovo | `XK` | | Kuwait | `KW` | | Kyrgyzstan | `KG` | | Laos | `LA` | | Latvia | `LV` | | Lebanon | `LB` | | Lesotho | `LS` | | Liberia | `LR` | | Libya | `LY` | | Liechtenstein | `LI` | | Lithuania | `LT` | | Luxembourg | `LU` | | Macao | `MO` | | North Macedonia | `MK` | | Madagascar | `MG` | | Malawi | `MW` | | Malaysia | `MY` | | Maldives | `MV` | | Mali | `ML` | | Malta | `MT` | | Martinique | `MQ` | | Mauritania | `MR` | | Mauritius | `MU` | | Mayotte | `YT` | | Mexico | `MX` | | Moldova | `MD` | | Monaco | `MC` | | Mongolia | `MN` | | Montenegro | `ME` | | Montserrat | `MS` | | Morocco | `MA` | | Mozambique | `MZ` | | Myanmar | `MM` | | Namibia | `NA` | | Nepal | `NP` | | Netherlands | `NL` | | Netherlands Antilles (deprecated) | `AN` | | New Caledonia | `NC` | | New Zealand | `NZ` | | Nicaragua | `NI` | | Niger | `NE` | | Nigeria | `NG` | | Norway | `NO` | | Oman | `OM` | | Pakistan | `PK` | | Panama | `PA` | | Papua New Guinea | `PG` | | Paraguay | `PY` | | Peru | `PE` | | Philippines | `PH` | | Poland | `PL` | | Portugal | `PT` | | Qatar | `QA` | | Réunion | `RE` | | Romania | `RO` | | Russia | `RU` | | Rwanda | `RW` | | Saint Barthélemy | `BL` | | Saint Helena, Ascension and Tristan da Cunha | `SH` | | Saint Kitts and Nevis | `KN` | | Saint Lucia | `LC` | | Saint Martin (French part) | `MF` | | Saint Vincent and the Grenadines | `VC` | | Samoa | `WS` | | San Marino | `SM` | | São Tomé and Príncipe | `ST` | | Saudi Arabia | `SA` | | Senegal | `SN` | | Serbia | `RS` | | Seychelles | `SC` | | Sierra Leone | `SL` | | Singapore | `SG` | | Sint Maarten (Dutch part) | `SX` | | Slovakia | `SK` | | Slovenia | `SI` | | Solomon Islands | `SB` | | Somalia | `SO` | | South Africa | `ZA` | | Spain | `ES` | | Sri Lanka | `LK` | | Suriname | `SR` | | Eswatini (formerly Swaziland) | `SZ` | | Sweden | `SE` | | Switzerland | `CH` | | Taiwan | `TW` | | Tajikistan | `TJ` | | Tanzania | `TZ` | | Thailand | `TH` | | Timor-Leste | `TL` | | Togo | `TG` | | Tonga | `TO` | | Trinidad and Tobago | `TT` | | Tunisia | `TN` | | Türkiye (Turkey) | `TR` | | Turks and Caicos Islands | `TC` | ### U–Z | Country | Code | | --------------------------------------------------------------------------------------------------------------------------------- | ---- | | Uganda | `UG` | | Ukraine | `UA` | | United Arab Emirates | `AE` | | United Kingdom | `GB` | | United States | `US` | | Uruguay | `UY` | | Uzbekistan | `UZ` | | Vanuatu | `VU` | | Venezuela | `VE` | | Vietnam | `VN` | | Virgin Islands (British) | `VG` | | Yemen | `YE` | | Zambia | `ZM` | | Zimbabwe | `ZW` | # Test Cards Supported test cards
{% @code-walkthrough/alert-block title="" message="The Adyen cards are enrolled in 3D Secure 2 security framework. To test 3D Secure 2 (advanced) scenarios, refer to test 3D Secure 2 authentication. One time password (OTP): 1234" type="warning" %}
Logo Card Type Card Number Expiry Date Security Code
American Express 3714 4963 5398 431 Mar-30 7373
Bancontact / Maestro 6703 4444 4444 4449 Mar-30 Not applicable
Bancontact / Visa 4871 0499 9999 9910 Mar-30 737
Cartes Bancaires / Visa Debit 4035 5014 2814 6300 Mar-30 737
Cartes Bancaires 4360 0000 0100 0005 Mar-30 737
China UnionPay (Credit) 6250 9470 0000 0014 Mar-30 123
China UnionPay (Debit) 6250 9460 0000 0016 Mar-30 123
Diners 3056 9309 0259 04 Mar-30 737
Discover 6011 1111 1111 1117 Mar-30 737
Maestro 5000 5500 0000 0029 Mar-30 Not applicable
Mastercard 5555 4444 3333 1111 Mar-30 737
Mastercard Credit 2222 4000 1000 0008 Mar-30 737
Visa 4917 6100 0000 0000 Mar-30 737
Visa Classic 4166 6766 6766 6746 Mar-30 737
The test cards listed above are for testing purposes only and cannot be used for real transactions.\ For more information on testing, refer to the [Adyen documentation](https://docs.adyen.com/development-resources/test-cards). # Configuration Configure markets, pricing, languages, redirection, and shipping for ESW on Shopify. Use these guides to configure your Shopify store for ESW. You’ll set up markets, pricing rules, storefront language and domain behavior, and shipping options. {% hint style="info" %} Start here after you’ve installed the ESW apps and your tenant is provisioned. See [Quick Start Guide](/shopify/shopify-native/quick-start-guide). {% endhint %}
Topic Link Cover image Cover image (dark)
Create a New Market /spaces/OZrcZKoZhyUFlsuSu228/pages/a0a2eadad4c5ff61afd8a05174598e97ac510f88 /files/6dFzRF5B85EJ1Vb0KdaC /files/Ido7cleFUYVAmgfmlFWP
Add Legal Messaging /spaces/OZrcZKoZhyUFlsuSu228/pages/f15b08c8a834ede660f52ce0482abd5d8015e6b4 /files/7x1Xs2CtkCjWe5c8uXhS /files/ZevqGZNOpELBKSvQSJNW
Product Pricing /spaces/OZrcZKoZhyUFlsuSu228/pages/c22ad658d9b3a2ccc6a10d8bb9b2403d1b91808b /files/l7pL6vchwKVIHlSWnsQZ /files/Zn9WWvNhKVBMLfohh8Wa
Languages & Domains /spaces/OZrcZKoZhyUFlsuSu228/pages/0418d191c245bb5f8df7b834e0d8ae79a29a34b1 /files/rwCcrlHMOKFmh0HRIMdt /files/h00yxq4iMKnY8UvMX3pG
Setup Automatic Country and Language Redirection /spaces/OZrcZKoZhyUFlsuSu228/pages/48a36f0a1493d5b196ac6d1f8447bb6f2cfacf75 /files/8uBoR4UpqWLFCtycVZoX /files/MOVOzmFm08yF5bliCROB
Shipping Methods, Rates, EDD for New Markets /spaces/OZrcZKoZhyUFlsuSu228/pages/32dd5cfcb789743704bc52d748fd8a08e1a5a130 /files/rLLdWJqjrcS1EayWHFXi /files/IKsGMbeQQmDgTeBCiTeD
# Create a New Market Create a Shopify market, set customer conditions, and inherit or customize settings for a new region. If your new market does not have a parent market, it will be created with your store’s default settings and no customizations. If you assign a parent market, the new market will automatically inherit the customizations from the parent market. {% stepper %} {% step %} ### Access Markets * From your **Shopify Admin**, navigate to **Markets**. * Click `Create market`
{% endstep %} {% step %} ### Enter Market Name In the **Name** section, enter a name for your new market. > (This name is for internal reference and not shown to customers.)
{% endstep %} {% step %} ### Select Publishing Status Choose the publishing status: * **Active:** Display the market immediately to customers. * **Draft:** Preview the market before making it live. {% endstep %} {% step %} ### Define Market Conditions
In the **Includes** section: * Click **Add Condition**. * Specify which customers the market should apply to, such as: * A specific **region** * A **company location** (for B2B) Click `Done` {% endstep %} {% step %} ### Review and Customize Settings * Review inherited settings from your **store defaults** or **parent market**. * Optionally customize: * **Currency** * **Catalogs** * **Online Store** * **Domain / Language** {% endstep %} {% step %} ### Save the Market
Click `Save` {% hint style="info" %} You can preview the shopper experience for any added languages to ensure proper localization before publishing. {% endhint %} {% endstep %} {% endstepper %} # Add Legal Messaging Add the ESW Privacy Notice block to Shopify checkout to meet legal requirements before go-live. To comply with legal requirements, you must add the [ESW Privacy Notice](https://esw.com/privacy-policy/) to your Shopify checkout page. This ensures that shoppers are informed about how their data is handled during the checkout process. The legal messaging is designed to integrate the ESW Privacy Notice into your Shopify store's checkout page. This messaging is essential for compliance with legal requirements. {% hint style="warning" %} ## Requirements * Install the **International App** and **Payments App**. * The privacy notice can be added to your Shopify checkout page at any stage after installing the International App and Payments App. * The ESW Privacy Notice must be added before go-live. {% endhint %} ## Legal Messaging To add the ESW Privacy Notice to your Shopify checkout page, follow these steps: {% stepper %} {% step %} ### Access Checkout Settings
* Access **Shopify Admin**. * From the left panel, navigate to **Settings → Checkout** {% endstep %} {% step %} ### Navigate to Configuration
* From the checkout **Configurations** section: * Click `Customize` {% endstep %} {% step %} ### Add Block
1. In the Checkout **Sidebar**, click **Add block**. 2. Select the block you want to add: **`ESW Privacy Policy`** {% endstep %} {% step %} ### Save Changes
Click **`Save`** at the top of the screen to publish the updated checkout layout. {% hint style="info" %} Blocks let you add custom content to your checkout page without editing theme code. {% endhint %} {% endstep %} {% endstepper %} # Product Pricing Choose a pricing approach and manage exchange rates per market in Shopify. {% hint style="danger" %} #### **Managed Process** * Product pricing configuration is implemented by ESW. * Contact your ESW onboarding manager. {% endhint %} Control how product prices display per market. Use Shopify markets for multi-currency pricing. Pick a pricing approach first. ### Pricing approaches Choose one approach per market.
Approach Cover image
ESW Pricing Advisor
Shows ESW duty and tax inclusive prices.
Use this for landed cost pricing.
/files/B0pkY8i9V3PqEfjxT72S
Fixed prices in Shopify
Set fixed product prices per market.
Use this for strict price control.
/files/kfPLZeNXDyQsnk75QR4Y
### Exchange rates in Shopify Shopify supports **automatic** and **manual** exchange rates. This impacts how prices convert per market. {% tabs %} {% tab title="Automatic exchange rates" %} * Prices convert using current market rates. * Converted prices can include fees and rounding. * Orders convert back to your store base currency. * Small variances can occur over time. {% endtab %} {% tab title="Manual exchange rates" %} Manual exchange rates help stabilize pricing. You set a fixed rate for a market. * You can’t set a manual rate for the primary market. * Manual rates use your store base currency. * Manual rates don’t apply to products with fixed prices. * You can combine manual rates with price adjustments. {% endtab %} {% endtabs %} ![](/files/c386a471eb7dcb4f5f99a82e0dfdc5db5c835425) ### Set a manual exchange rate Follow these steps to activate a manual exchange rate. {% stepper %} {% step %} ### Access Markets From your **Shopify Admin**, go to **Settings → Markets**. {% endstep %} {% step %} ### Select Market Open the market you want to update. {% endstep %} {% step %} ### Manage Exchange Rate Go to **Products and Pricing → Manage exchange rate**. {% endstep %} {% step %} ### Set Manual Exchange Rate 1. Select **Manual**. 2. Enter the exchange rate. 3. Click **`Save`**. {% hint style="info" icon="list-dropdown" %} ### Important Note * Switching to **Automatic** rates deactivates manual rates. * Changing the **base currency** also deactivates manual rates. * Deactivation does not delete saved manual rates. * You can reactivate manual rates later. {% endhint %} {% endstep %} {% endstepper %} # Languages & Domains Add storefront languages and assign languages and domains per market in Shopify. {% hint style="danger" %} #### **Managed Process** * Languages and Domains configuration is implemented by ESW. * Contact your ESW onboarding manager. {% endhint %} Use Shopify **Languages** to add storefront languages. Use **Markets** to assign languages and domains per region. ### Before you start Adding a language does not translate your full store. Shopify auto-translates only supported theme and checkout content. For everything else, upload translations or use a translation app. **Translate & Adapt** is the common default. {% hint style="warning" %} To manage **languages per market**, you need international domains configured (subfolders, domains, or subdomains). Without international domains, language settings apply across all active markets. {% endhint %} ### Add a language to your store {% stepper %} {% step %} ### Open language settings From your **Shopify Admin**, go to **Settings → Languages**. {% endstep %} {% step %} ### Add the language 1. Click **Add language**. 2. Select the language from the list. {% endstep %} {% step %} ### Choose where it applies * If you have **one market** or **no international domains**, click **Add**. * If you have **multiple markets** with international domains: 1. Click **Next**. 2. Select the markets to enable the language for. 3. Click **Done**. {% endstep %} {% step %} ### Add translations * Import translations with **Translate & Adapt**, or another translation app. * Confirm key storefront pages look correct before publishing. {% endstep %} {% endstepper %} ### Publish a language {% stepper %} {% step %} ### Open language settings From your **Shopify Admin**, go to **Settings → Languages**. {% endstep %} {% step %} ### Publish 1. Under **Unpublished languages**, open **… (More actions)**. 2. Select **Publish**. 3. Click **Save**. {% endstep %} {% endstepper %} {% hint style="info" %} If you publish without full translations, Shopify will prompt you. Untranslated content will stay in the default language. {% endhint %} ### Assign languages and domains to a market You must add the language to your store first. Then assign it to the market. ![](/files/634a74b5b31526eaea13ef7bb5785373318334ce) {% stepper %} {% step %} ### Access Markets From your **Shopify Admin**, go to **Settings → Markets**. {% endstep %} {% step %} ### Select the market Open the market you want to configure. {% endstep %} {% step %} ### Open Languages and domains Click **Languages and domains**. {% endstep %} {% step %} ### Add a language 1. Click **Add languages**. 2. Under **Not added to this market**, select the language. {% endstep %} {% step %} ### (Optional) Set domain and default language Use the same **Languages and domains** screen to: * Confirm the market domain setup. * Choose the default language for the market. {% endstep %} {% endstepper %} ### Related topics
Topic Link
Setup Automatic Country and Language Redirection /spaces/OZrcZKoZhyUFlsuSu228/pages/48a36f0a1493d5b196ac6d1f8447bb6f2cfacf75
Product Pricing /spaces/OZrcZKoZhyUFlsuSu228/pages/c22ad658d9b3a2ccc6a10d8bb9b2403d1b91808b
# Setup Automatic Country and Language Redirection Automatically route shoppers to the right market and language using location and browser settings. {% hint style="danger" %} #### Managed Process * Configuration is implemented by ESW. * Contact your ESW onboarding manager. {% endhint %} Automatic redirection routes shoppers to the best storefront experience. It uses **location** and **browser language**.
{% hint style="warning" %} ### Prerequisites * Your markets are configured in **Settings → Markets**. * Your languages are added, translated, and published. * Languages are assigned to the right markets. Refer to [Languages & Domains](/shopify/shopify-native/configuration/languages-and-domains) for more info. {% endhint %} ### Enable country/region redirection This redirects shoppers to the correct market. It can change domain, subdomain, or subfolder. {% stepper %} {% step %} ### Open Preferences From your **Shopify Admin**, go to **Online Store → Preferences**. {% endstep %} {% step %} ### Turn on Country/Region In **Automatic redirection**, enable **Country/region**. {% endstep %} {% step %} ### Save Click **Save**. {% endstep %} {% endstepper %} {% hint style="info" %} Automatic redirection does not replace a manual selector. Add country/language selectors to your theme, or use a selector app. {% endhint %} ### How country/region redirection behaves #### Markets using dedicated domains Dedicated domains include: * Dedicated domain (example: `example.ca`) * Subdomain (example: `ca.example.com`) * Subfolder (example: `example.com/en-ca`) Shoppers are redirected to the matching market URL. Search engines can index each market URL separately. #### Markets using a shared domain Shared domain means multiple markets use the same domain. Shopify adjusts content without changing the domain. Example: * US market: `example.com` in `USD` * Canada market: `example.com` in `CAD` Search engines won’t index separate market domains. ### EU behavior (ccTLD) EU legislation restricts some automatic redirects. If a shopper visits a **country-code top-level domain (ccTLD)**, Shopify does not auto-redirect them to a different ccTLD. Example: * French shopper visits `example.de` * They are not redirected to `example.fr` If you use a non-country domain (like `.com`), automatic redirection can apply. {% hint style="info" %} For EU stores, consider a geolocation or recommendation app. Use it to suggest the “right” store and let the shopper choose. {% endhint %}

EU ccTLD list
Common EU ccTLDs: `.at`, `.be`, `.bg`, `.hr`, `.cy`, `.cz`, `.dk`, `.ee`, `.fi`, `.fr`, `.de`, `.gr`, `.hu`, `.ie`, `.it`, `.lv`, `.lt`, `.lu`, `.mt`, `.nl`, `.pl`, `.pt`, `.ro`, `.sk`, `.si`, `.es`, `.se`, `.eu`
### Enable language redirection Language redirection switches to the best-matching language. It uses the shopper’s browser language. #### Requirements * The language is added to your store. * The language is published. * The language is assigned to the relevant market. * Translations exist for the storefront content. Example: * Domain: `example.ca` * Default language: English * Browser language: French * Result: shopper lands on `example.ca/fr` {% stepper %} {% step %} ### Open Preferences From your **Shopify Admin**, go to **Online Store → Preferences**. {% endstep %} {% step %} ### Turn on Language In **Automatic redirection**, enable **Language**. {% endstep %} {% step %} ### Save Click **Save**. {% endstep %} {% endstepper %} ### Related topics
Topic Link
Languages & Domains /spaces/69bGsllGv04t8wHIHruV/pages/0418d191c245bb5f8df7b834e0d8ae79a29a34b1
Create a New Market /spaces/69bGsllGv04t8wHIHruV/pages/a0a2eadad4c5ff61afd8a05174598e97ac510f88
# Shipping Methods, Rates, EDD for New Markets Set up fulfillment locations and shipping rates, including transit times for estimated delivery dates (EDD). {% hint style="danger" %} #### Managed Process * Configuration is implemented by ESW. * Contact your ESW onboarding manager. {% endhint %} Configure shipping for a new market. You’ll typically do two things: * Set up **fulfillment locations**. * Configure **shipping rates** and **transit times** (EDD). ### Fulfillment locations A location is any place (or app) that fulfills orders or holds inventory. Examples include warehouses, retail stores, and dropshippers. Use multiple locations to: * Track inventory by site. * Fulfill from the best location. * Control fulfillment priority. ### Add a location
New locations default to being available for online fulfillment. They also appear at the bottom of your fulfillment priority list. {% stepper %} {% step %} ### Access Locations From your **Shopify Admin**, go to **Settings → Locations**. {% endstep %} {% step %} ### Add a New Location In **All locations**, click **Add location**. {% endstep %} {% step %} ### Enter Location Details In **Location details**, set: * **Name** * **Address** {% endstep %} {% step %} ### Inventory Availability (Optional) To prevent online orders from routing to this location, disable: **Inventory at this location is available to fulfill online orders** {% endstep %} {% step %} ### Save the Location Click **Save**. {% endstep %} {% endstepper %} {% hint style="info" %} If you don’t want products stocked at every location, adjust inventory per location in **Products → Inventory**. {% endhint %} ### Shipping rates and EDD Shipping rates control what shoppers see at checkout. Transit times can drive **estimated delivery dates (EDD)** where enabled. Flat shipping rates let you charge a fixed amount for shipping during checkout. You can scope rates to a shipping zone. You can also add weight or price conditions. ### Add a shipping rate
{% stepper %} {% step %} ### Access Shipping Settings From your **Shopify Admin**, go to **Settings → Shipping and delivery**. {% endstep %} {% step %} ### Select Shipping Profile In **Shipping**, open the shipping profile you want to edit. {% endstep %} {% step %} ### Add Shipping Rate Next to the target shipping **zone**, click **Add rate**. Then choose: * A **transit time** (for delivery expectations / EDD), or * **Custom flat rate** (for a named flat price). {% endstep %} {% step %} ### Add Delivery Description (Optional) If you use **Custom flat rate**, add a short description. Keep it to 25 characters when possible. {% endstep %} {% step %} ### Enter Shipping Rate Enter the shipping price. {% endstep %} {% step %} ### (Optional) Add Conditions Add weight-based or price-based conditions if needed. {% endstep %} {% step %} ### Review Checkout Preview Use the preview to confirm the rate and messaging. {% endstep %} {% step %} ### Save Shipping Rate Click **Done**, then **Save**. {% endstep %} {% endstepper %} # Integration Connect Shopify and ESW using webhooks and ESW APIs for catalog, pricing, and order lifecycle sync. {% hint style="danger" icon="hand-holding-box" %} #### **Managed Process** * Integration is implemented by ESW. * Contact your ESW onboarding manager. {% endhint %}
Topic Link Cover image Cover image (dark) Cover image (dark)
Integration Overview /spaces/OZrcZKoZhyUFlsuSu228/pages/c51fcf032ce857f3d496ac1a144f97ac63c72779 /files/rLLdWJqjrcS1EayWHFXi /files/IKsGMbeQQmDgTeBCiTeD /files/IKsGMbeQQmDgTeBCiTeD
Product Catalog Sync /spaces/OZrcZKoZhyUFlsuSu228/pages/95e056cc6dfc121c604f5ea3d9c3b8ac0f214a8d /files/8uBoR4UpqWLFCtycVZoX /files/MOVOzmFm08yF5bliCROB /files/MOVOzmFm08yF5bliCROB
Pricing Import /spaces/OZrcZKoZhyUFlsuSu228/pages/beb4a39dc642fb7c9ff52bb6402c350bb98ff47c /files/rwCcrlHMOKFmh0HRIMdt /files/h00yxq4iMKnY8UvMX3pG
Order Management /spaces/OZrcZKoZhyUFlsuSu228/pages/87129aebd2293f4c97a2bd786b43a3faf3aa3011 /files/l7pL6vchwKVIHlSWnsQZ /files/Zn9WWvNhKVBMLfohh8Wa
Shipping Address Update /spaces/OZrcZKoZhyUFlsuSu228/pages/c2f06d89166f7979ba488c174a09bf8dbc3b2849 /files/7x1Xs2CtkCjWe5c8uXhS /files/ZevqGZNOpELBKSvQSJNW
Order and Item-Level Cancellations /spaces/OZrcZKoZhyUFlsuSu228/pages/465a1bf0f89a80277189e786d587a8c0a0e877cf /files/6dFzRF5B85EJ1Vb0KdaC /files/Ido7cleFUYVAmgfmlFWP
Appeasements /spaces/OZrcZKoZhyUFlsuSu228/pages/4ec858a0893c557fff20c3b0b4b7f12acb7da209 /files/d7XJa1US1IBoAfj6XJMT /files/ZL04KZjR6xCeHBD20H1Y
# Integration Overview How Shopify checkout, webhooks, and ESW order import fit together. {% hint style="danger" %} #### Managed Process * Integration is implemented by ESW. * Contact your ESW onboarding manager. {% endhint %} Shopify’s native checkout for the shopper purchase flow. After checkout, the app imports Shopify order into ESW as an **offline order**. ESW then drives the downstream operational flow. *** * Logistics and shipping orchestration * Compliance * Order tracking and post‑purchase workflows ### High-level flow ![](/files/9f379d6e0a1826eecbea2818a5ede4f00a42dca2) {% stepper %} {% step %} ### Shopper checks out in Shopify The shopper completes checkout in Shopify. Shopify creates the order in your store. {% endstep %} {% step %} ### Shopify notifies your integration Your integration receives order events through Shopify webhooks. Typical topic: `orders/create`. {% endstep %} {% step %} ### Your integration imports the order into ESW Map Shopify order data to the ESW order model. Submit it to ESW as an **offline order** (or your ESW-required type). {% endstep %} {% step %} ### ESW fulfills and updates flow back to Shopify ESW handles fulfillment execution. Shipment, tracking, and status updates should be reflected back in Shopify. {% endstep %} {% endstepper %} ### Related topics
Topic Link
Order Management /spaces/69bGsllGv04t8wHIHruV/pages/87129aebd2293f4c97a2bd786b43a3faf3aa3011
Product Catalog Sync /spaces/69bGsllGv04t8wHIHruV/pages/95e056cc6dfc121c604f5ea3d9c3b8ac0f214a8d
Pricing Import /spaces/69bGsllGv04t8wHIHruV/pages/beb4a39dc642fb7c9ff52bb6402c350bb98ff47c
Shipping Methods, Rates, EDD for New Markets /spaces/69bGsllGv04t8wHIHruV/pages/32dd5cfcb789743704bc52d748fd8a08e1a5a130
# Product Catalog Sync Sync Shopify product and variant updates to ESW using webhooks and the ESW Catalog API. Sync product and variant changes from Shopify into ESW. Use Shopify **product webhooks** to detect changes. Then upsert the latest catalog data to ESW using the **ESW Catalog API**. ### Prerequisites * You have an integration service that can receive Shopify webhooks. * You have ESW Catalog API credentials and the target catalog schema. * You’ve defined your *source of truth* for pricing. {% hint style="warning" %} Shopify webhooks are best-effort delivery. {% endhint %} ### Webhook-driven sync flow {% stepper %} {% step %} ### Subscribe to Shopify product webhooks Create webhook subscriptions for the product lifecycle events you use. Common topics: * `products/create` * `products/update` * `products/delete` #### Shopify docs [Webhooks](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook) {% endstep %} {% step %} ### Receive and validate the webhook When a webhook fires: * Verify the request is from Shopify (HMAC validation). * Parse the product payload. * Deduplicate events (Shopify can retry deliveries). {% endstep %} {% step %} ### Map Shopify fields to the ESW catalog schema Transform Shopify product + variant data into the format ESW expects. Typical fields to align: * Product and variant identifiers * SKU (per variant) * Title, description, and images * Options (size, color) and availability * Taxonomy / category mapping (if required by your ESW setup) {% endstep %} {% step %} ### Upsert catalog data in ESW Call the ESW Catalog API to create or update the product record. Recommended behaviors: * Make the upsert idempotent. * Retry transient failures. * Log the ESW response for traceability. {% endstep %} {% step %} ### Handle deletes and unpublishing Decide what a Shopify delete/unpublish means for ESW: * Remove the item from the ESW catalog, or * Mark it inactive / not purchasable. {% endstep %} {% endstepper %} # Pricing Import Calculate localized prices with ESW Pricing Advisor and import fixed prices into Shopify markets. Import localized prices from **ESW Pricing Advisor** into Shopify markets. Use ESW to calculate market-specific prices. Then write fixed prices to Shopify using the Admin GraphQL API. ### Prerequisites * Your Shopify **markets** and **currencies** are set up. * Your products and variants exist in Shopify. * If ESW relies on your Shopify catalog, see [Product Catalog Sync](broken://spaces/69bGsllGv04t8wHIHruV/pages/95e056cc6dfc121c604f5ea3d9c3b8ac0f214a8d). * You have credentials for: * ESW Pricing Advisor API * Shopify Admin API (GraphQL) {% hint style="info" %} Pricing imports are usually batch jobs. Run them on a schedule and after major catalog changes. {% endhint %} ### Pricing import flow {% stepper %} {% step %} ### Define your pricing scope Decide which combinations you price. Typical dimensions: * Market (country/region) * Currency * Variant (SKU) Keep a stable mapping between a Shopify market and your ESW pricing inputs. {% endstep %} {% step %} ### Fetch pricing inputs from ESW Call the ESW Pricing Advisor API per market to retrieve the rules needed to price. Common inputs: * Exchange rates * Duties and taxes * Rounding rules Fetch the data for every target market and currency pair. {% endstep %} {% step %} ### Calculate the final price per variant For each variant/SKU: * Apply the ESW rules for the market. * Produce the price you want shoppers to see. Store the result with: * Market * Currency * Variant/SKU * Effective timestamp (optional) {% endstep %} {% step %} ### Upsert fixed prices into Shopify Write the calculated prices to Shopify as fixed prices. Implementation notes: * Use the Admin GraphQL API. * Batch updates to stay within rate limits. * Make updates idempotent. #### Shopify mutation [priceListFixedPricesAdd](https://shopify.dev/docs/api/admin-graphql/latest/mutations/priceListFixedPricesAdd). {% endstep %} {% step %} ### Validate and monitor Spot-check a few products in each market. Then monitor for: * Missing SKUs * Large price deltas * Failed writes / throttling {% endstep %} {% endstepper %} ### Shopify reference links {% tabs %} {% tab title="Fixed prices by country/market" %} [Product prices by country (Shopify Help)](https://help.shopify.com/en/manual/international/pricing/product-prices-by-country#set-fixed-product-prices-using-the-shopify-api) {% endtab %} {% tab title="Fixed prices for specific variants" %} [Set fixed prices for specific variants (Shopify Dev)](https://shopify.dev/docs/apps/build/markets/build-catalog#step-3-set-fixed-prices-for-specific-product-variants) {% endtab %} {% endtabs %} ### **How duties and taxes calculated and displayed** Duties and taxes are calculated using a **dedicated ESW-Shopify connector**. * **Calculation:** When a shopper enters their shipping address, Shopify issues a request to the ESW calculator. If the market is configured for **DDP (Delivery Duties Paid)**, the calculator returns the specific duties and taxes for the delivery. * **Display:** Checkout displays merchandise, shipping, duties, and taxes as **separate components** to ensure transparency for international shoppers. * **Treatment:** Duties and taxes are calculated based on the **full merchandise value**, even when gift cards are used, as gift cards are treated as a form of payment rather than a discount. # Order Management Sync orders, fulfillment, and cancellations between Shopify and ESW. Shopify sends order events via webhooks. Your integration posts orders to ESW. ESW fulfillment updates flow back to Shopify. ### Prerequisites * You have an integration service that can receive Shopify webhooks. * You have access to: * Shopify Admin API (REST/GraphQL) * ESW Order APIs for order import and updates * You’ve decided which system “owns” downstream changes: * Cancellations * Partial cancellations (item-level) * Fulfillment and tracking {% hint style="info" %} Treat all inbound events as at-least-once delivery. {% endhint %} ### Webhook-driven order flow {% stepper %} {% step %} ### Subscribe to Shopify order webhooks Create webhook subscriptions for the topics you support. Common topics: * `orders/create` * `orders/updated` * `orders/cancelled` #### Shopify : [Webhooks](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook). {% endstep %} {% step %} ### Receive and validate the webhook When a webhook fires: * Verify the request is from Shopify (HMAC validation). * Deduplicate on webhook id / event id. * Enrich the payload if you need full order detail. {% endstep %} {% step %} ### Import the order into ESW Map Shopify order data to the ESW order model. Then submit the order to ESW as an **offline order** (or your ESW-required type). Typical mapping considerations: * Order id, timestamps, and customer identifiers * Line items (variant id / SKU), quantities, discounts * Shipping method and costs * Taxes and duty handling (based on your ESW setup) {% endstep %} {% step %} ### Apply ESW fulfillment updates back to Shopify When ESW creates shipments or updates fulfillment status: * Capture ESW shipment/tracking events. * Update the Shopify fulfillment with: * Tracking number(s) * Carrier * Fulfillment status #### Shopify reference : [fulfillmentCreateV2](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentCreateV2). {% endstep %} {% step %} ### Synchronize cancellations and item-level changes Decide which events you propagate and when. Typical approaches: * Shopify cancellation triggers ESW cancellation. * ESW cancellation triggers Shopify cancellation or adjustments. #### Shopify : * [orders/cancelled webhook](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook#event-topics-orders-cancelled) * [orders/updated webhook](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook#event-topics-orders-updated) {% endstep %} {% step %} ### Reconcile and monitor Add a daily job to catch missed events. Track and alert on: * Orders not imported to ESW * Fulfillment updates failing to write to Shopify * Repeated webhook retries / throttling {% endstep %} {% endstepper %} # Shipping Address Update Capture post-purchase shipping address changes in Shopify and sync them to ESW. Sync shipping address changes between Shopify and ESW. Use Shopify order update webhooks to detect changes. Then push the new address to ESW for the same order. ### Prerequisites * You have an integration service that can receive Shopify webhooks. * You can call the Shopify Admin API (REST/GraphQL). * You can call the ESW order update endpoint for contact details. * You’ve defined when address changes are allowed. * Example: only before fulfillment is created. {% hint style="info" %} Treat Shopify webhooks as at-least-once delivery. {% endhint %} ### Webhook-driven address update flow {% stepper %} {% step %} ### Subscribe to `orders/updated` Use `orders/updated` to catch post-purchase changes. #### Shopify docs [orders/updated](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook#event-topics-orders-updated). {% endstep %} {% step %} ### Receive and validate the webhook When the webhook fires: * Validate the Shopify HMAC signature. * Deduplicate on webhook id / event id. * Re-fetch the order if you need full, current data. {% endstep %} {% step %} ### Detect a shipping address change `orders/updated` fires for many order edits. Filter for shipping address deltas. Compare these fields at minimum: * Name * Address lines * City * Region / state * Postal code * Country code * Phone (if you sync it to ESW) {% endstep %} {% step %} ### Map to ESW contact details Transform the Shopify shipping address into the ESW format. Send the order identifier ESW expects. Keep a stable mapping between: * Shopify order id / name * ESW order reference {% endstep %} {% step %} ### Update ESW Call the ESW **Update Contact Details** API for the order. Recommended behavior: * Retry transient failures. * Stop retrying once the order is no longer editable in ESW. * Log ESW responses for traceability. {% endstep %} {% step %} ### Monitor and reconcile Alert on failures and repeated retries. Add a daily job to reconcile recent orders if needed. {% endstep %} {% endstepper %} # Order and Item-Level Cancellations Keep cancellation state in sync between Shopify and ESW, including partial (item-level) cancels. Sync cancellations between Shopify and ESW. Use Shopify webhooks to capture changes. Then apply the equivalent cancellation in the other system. ### Prerequisites * You have an integration service that can receive Shopify webhooks. * You can call: * Shopify Admin API (REST/GraphQL) * ESW order update / cancellation endpoints * You’ve decided which system “owns” cancellations after order import. * Shopify-led cancellations (CS ops in Shopify) * ESW-led cancellations (warehouse / carrier constraints) {% hint style="info" %} Shopify and ESW can both emit retries or duplicate events. {% endhint %} ### Webhook-driven cancellation flow {% stepper %} {% step %} ### Subscribe to Shopify cancellation signals Use these topics depending on your operating model: * `orders/cancelled` for full-order cancellations. * `orders/updated` if you represent partial cancels as edits/adjustments. #### Shopify docs : * [orders/cancelled](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook#event-topics-orders-cancelled) * [orders/updated](https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook#event-topics-orders-updated) {% endstep %} {% step %} ### Receive, validate, and enrich the event When a webhook fires: * Validate the Shopify HMAC signature. * Deduplicate on webhook id / event id. * Fetch the latest order state if needed for line-level details. {% endstep %} {% step %} ### Decide what changed (full vs partial) Normalize Shopify changes into one of these intents: * **Full cancellation**: the entire order is cancelled. * **Partial cancellation**: one or more items are cancelled/removed/adjusted. Document your “partial cancel” representation. Common patterns: * ESW line-item cancel, Shopify uses refunds/adjustments. * Shopify line-item edits, ESW uses item-level cancellation calls. {% endstep %} {% step %} ### Apply Shopify-led cancellations to ESW If Shopify is the source of truth: * Map the Shopify order id to the ESW order reference. * Send the cancellation intent to ESW: * Full order cancellation, or * Item-level cancellation with quantities and reasons (if supported) Only cancel what ESW can still cancel. Stop and alert if ESW has already shipped. {% endstep %} {% step %} ### Apply ESW-led cancellations to Shopify If ESW can cancel post-import: * Monitor ESW for cancellation events (order or line-item). * Apply the corresponding update in Shopify using your chosen mechanism. #### Shopify reference [orderCancel](https://shopify.dev/docs/api/admin-graphql/latest/mutations/orderCancel). {% endstep %} {% step %} ### Reconcile and monitor Track and alert on: * Cancellation write failures to either system * Conflicts (already fulfilled, already refunded, already cancelled) * Repeated retries / throttling Add a daily reconciliation job for recent orders. {% endstep %} {% endstepper %} # Appeasements Reflect ESW-initiated appeasements (refunds or compensation) back into Shopify. Sync appeasements between ESW and Shopify. ESW can issue refunds or compensation after order import. Mirror that financial state in Shopify to keep reporting aligned. ### Prerequisites * You can receive appeasement events from ESW. * Webhook, message bus, or scheduled polling. * You can call the Shopify Admin API (REST/GraphQL). * You have a stable mapping between: * ESW order reference * Shopify order id / name * You’ve defined your Shopify representation of appeasements. * Refund against line items. * Refund at order level. * Non-item compensation (gift card or custom item). {% hint style="info" %} Treat ESW events as at-least-once delivery. {% endhint %} ### ESW-driven appeasement flow {% stepper %} {% step %} ### Capture appeasements in ESW Listen for ESW appeasement activity at: * Order level * Item level Capture these fields at minimum: * ESW order reference * Appeasement id (or another unique event id) * Amount and currency * Affected items and quantities (if item-level) * Reason code / notes * Timestamp {% endstep %} {% step %} ### Normalize and validate the event Before updating Shopify: * Confirm the order exists in Shopify. * Confirm currency matches the Shopify order currency. * Confirm the appeasement is allowed for the order state. * Example: don’t refund beyond captured/paid totals. * Deduplicate by appeasement id. {% endstep %} {% step %} ### Map the appeasement to a Shopify action Decide the Shopify primitive you will use: * **Refund** for money back to the shopper. * **Adjustment** or custom line for non-item compensation. Keep the mapping deterministic. The same ESW appeasement should always produce the same Shopify mutation. {% endstep %} {% step %} ### Apply the update in Shopify Create the corresponding refund or adjustment in Shopify. #### Shopify reference [refundCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/refundCreate). Recommended behavior: * Store the Shopify refund id you created. * Retry transient failures. * Stop and alert on validation errors. {% endstep %} {% step %} ### Reconcile and monitor Track and alert on: * Shopify updates that fail or time out * Mismatched totals between ESW and Shopify * Duplicate events that would trigger double refunds Add a daily job to reconcile recent appeasements if needed. {% endstep %} {% endstepper %} ### Related topics
Topic Link
Order Management /spaces/69bGsllGv04t8wHIHruV/pages/87129aebd2293f4c97a2bd786b43a3faf3aa3011
Order and Item-Level Cancellations /spaces/69bGsllGv04t8wHIHruV/pages/465a1bf0f89a80277189e786d587a8c0a0e877cf
Shipping Address Update /spaces/69bGsllGv04t8wHIHruV/pages/c2f06d89166f7979ba488c174a09bf8dbc3b2849
# Integration Workflow Overview of the ESW-managed Shopify integration workflow across catalog sync, pricing import, order ingestion, address updates, fulfilment, and cancellations. {% hint style="danger" %} #### Managed Process * Integration is implemented by ESW. * Contact your ESW onboarding manager. {% endhint %} # Product Catalog Integration The app syncs Shopify product changes to ESW using Shopify webhooks and the ESW Catalog API. ### 1. Shopify Webhooks The app subscribes to Shopify product creation and update events.
Cover image Cover image (dark)
Shopify Webhook
products/create /files/d7XJa1US1IBoAfj6XJMT /files/ZL04KZjR6xCeHBD20H1Y https://shopify.dev/docs/api/admin-rest/latest/resources/webhook#event-topics-products-create

Shopify Webhook
products/update /files/rLLdWJqjrcS1EayWHFXi /files/IKsGMbeQQmDgTeBCiTeD https://shopify.dev/docs/api/admin-rest/latest/resources/webhook#event-topics-products-update
### 2. API Integration After receiving the product data, the app calls the ESW Catalog API endpoint {% hint style="info" %} #### **ESW API** Product data from Shopify is posted to ESW using the ESW Catalog API. {% endhint %} ## POST /api/v2/RetailerCatalog > Allows a retailer to upload a catalog that will be subject to validation processing. ```json {"openapi":"3.0.4","info":{"title":"Customs.Catalog.Api","version":"2.0.1447.0"},"servers":[{"url":"https://logistics-customscatalog-api.sandbox.eshopworld.com/"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Please insert JWT with Bearer into field","name":"Authorization","in":"header"}},"schemas":{"Customs.Catalog.Domain.Pkg.Models.DTO.RetailerCatalogProduct":{"required":["countryOfOrigin","description","material","name","productCode"],"type":"object","properties":{"productCode":{"minLength":1,"type":"string","description":"(Required) The brand's unique master identifier or SKU (Stock Keeping Unit)."},"name":{"minLength":1,"type":"string","description":"(Required) The name of the product."},"description":{"minLength":1,"type":"string","description":"(Required) The short description of the product."},"material":{"minLength":1,"type":"string","description":"(Required) A description of the material that the product is made of."},"countryOfOrigin":{"$ref":"#/components/schemas/Customs.Catalog.Common.Pkg.Product.CountryIso"},"hsCode":{"type":"string","description":"The brand’s HSCode of the product.This should be a minimum of 6 digits.","nullable":true},"hsCodeRegion":{"$ref":"#/components/schemas/Customs.Catalog.Common.Pkg.Product.Region"},"parentProductCode":{"type":"string","description":"SKU for a group of products that come in different versions (variants).","nullable":true},"category":{"$ref":"#/components/schemas/Customs.Catalog.Common.Pkg.Product.Category"},"categoryDesc":{"type":"string","description":"eShopWorld category description for the product.","nullable":true,"readOnly":true},"gender":{"$ref":"#/components/schemas/Customs.Catalog.Common.Pkg.Product.Gender"},"ageGroup":{"$ref":"#/components/schemas/Customs.Catalog.Common.Pkg.Product.AgeGroup"},"size":{"type":"string","description":"(Optional) The size of the product.","nullable":true},"weight":{"type":"number","description":"(Optional*) The weight of the product in the associated WeightUnit.\n*This field is mandatory if you specify a weight unit.","format":"double","nullable":true},"weightUnit":{"$ref":"#/components/schemas/Customs.Catalog.Common.Pkg.Product.WeightUnit"},"url":{"type":"string","description":"(Optional*) The product’s landing page.\n*This field is mandatory when Shipping to Russia and Japan.","nullable":true},"imageUrl":{"type":"string","description":"(Optional) The URL of the product’s main image thumbnail.","nullable":true},"unitPrice":{"$ref":"#/components/schemas/Customs.Catalog.Domain.Pkg.Models.DTO.RetailerPrice"},"dangerousGoods":{"type":"boolean","description":"(Optional) Indicates if the product is classified a DangerousGood or Hazardous Material (HazMat).","nullable":true},"isCustomized":{"type":"boolean","description":"(Optional) Indicates if the product has been customized in any way from its Original Design.","nullable":true},"additionalProductCode":{"type":"string","description":"(Optional) An additional product code, or unique identifier,\nsuch as the manufacturer’s product code or SKU (Stock Keeping Unit),\nthat may be on or attached to the product.","nullable":true},"variantProductCode":{"type":"string","description":"(Optional) Another version of the brand's unique master identifier or SKU (Stock Keeping Unit).","nullable":true},"restrictions":{"type":"array","items":{"$ref":"#/components/schemas/Customs.Catalog.Domain.Pkg.Models.DTO.RestrictionDto"},"description":"(Optional) Identifies when a product should be Restricted from Sale in Certain Countries.","nullable":true},"isRestricted":{"type":"boolean","description":"(Optional) Identifies restriction on a product regardless of what country it's being sold to or any other product attributes.","nullable":true},"mid":{"type":"string","description":"(Optional) Identifies the Manufacturer ID.","nullable":true},"midAddressZip":{"type":"string","description":"(Optional) Identifies the Manufacturer's ZipCode","nullable":true},"additionalInformation":{"type":"string","description":"(Optional) Any other additional information about the product.","nullable":true},"categoryInformation":{"type":"string","description":"(Optional) Any other additional information about the product category.","nullable":true},"isSubscription":{"type":"boolean","description":"(Optional) Identifies if the product is a Subscription based product.","nullable":true},"eccn":{"type":"string","description":"ECCN","nullable":true},"ean":{"pattern":"^\\d{8}$|^\\d{13}$","type":"string","description":"(Optional) EAN","nullable":true},"upc":{"pattern":"^\\d{8}$|^\\d{12}$","type":"string","description":"(Optional) UPC","nullable":true}},"additionalProperties":false,"description":"Retailer Product Object"},"Customs.Catalog.Common.Pkg.Product.CountryIso":{"enum":["AD","AE","AF","AG","AI","AL","AM","AN","AO","AQ","AR","AS","AT","AU","AW","AX","AZ","BA","BB","BD","BE","BF","BG","BH","BI","BJ","BL","BM","BN","BO","BQ","BR","BS","BT","BV","BW","BY","BZ","CA","CC","CD","CF","CG","CH","CI","CK","CL","CM","CN","CO","CR","CS","CU","CV","CW","CX","CY","CZ","DE","DJ","DK","DM","DO","DZ","EC","EE","EG","EH","ER","ES","ET","FI","FJ","FK","FM","FO","FR","GA","GB","GD","GE","GF","GG","GH","GI","GL","GM","GN","GP","GQ","GR","GS","GT","GU","GW","GY","HK","HM","HN","HR","HT","HU","ID","IE","IL","IM","IN","IO","IQ","IR","IS","IT","JE","JM","JO","JP","KE","KG","KH","KI","KM","KN","KP","KR","KW","KY","KZ","LA","LB","LC","LI","LK","LR","LS","LT","LU","LV","LY","MA","MC","MD","ME","MF","MG","MH","MK","ML","MM","MN","MO","MP","MQ","MR","MS","MT","MU","MV","MW","MX","MY","MZ","NA","NC","NE","NF","NG","NI","NL","NO","NP","NR","NU","NZ","OM","PA","PE","PF","PG","PH","PK","PL","PM","PN","PR","PS","PT","PW","PY","QA","RE","RO","RS","RU","RW","SA","SB","SC","SD","SE","SG","SH","SI","SJ","SK","SL","SM","SN","SO","SR","SS","ST","SV","SX","SY","SZ","TC","TD","TF","TG","TH","TJ","TK","TL","TM","TN","TO","TR","TT","TV","TW","TZ","UA","UG","UM","US","UY","UZ","VA","VC","VE","VG","VI","VN","VU","WF","WS","XK","YE","YT","ZA","ZM","ZW","TP"],"type":"string"},"Customs.Catalog.Common.Pkg.Product.Region":{"enum":["AD","AE","AL","AM","AU","AZ","BA","BY","BH","CA","CH","CL","CN","CO","EG","EU","GE","GI","HK","ID","IS","IL","IN","JP","KR","KW","KZ","LI","MA","MD","ME","MK","MX","MY","NO","NZ","PH","PR","QA","RS","RU","SA","SG","SM","TH","TL","TR","TW","UA","US","VN","XROW","ZA","XK","BR","MM","MO","PY","SK","AR","PE","DO","JO","KG","OM","BO","AF","AG","AI","AN","AO","AS","AW","BB","BD","BM","BZ","CR","CS","DZ","EC","ET","IO","IQ","FJ","JM","KE","KH","LA","LK","LR","LS","LY","MF","ML","MN","MQ","MR","MS","MV","MW","MZ","NA","NF","NG","NI","NP","NR","NU","PA","PK","PS","RW","SN","SO","SR","SS","SV","SX","TG","TT","TZ","UG","UY","UZ","VE","VU","WF","WS","YE","ZM","ZW","GB","TP","GW","JE","GT","KY","BN","TC","GP","GF","DM","GD","RE","LC","HN","KN","BF","BJ","BS","BW","CF","CG","CK","CM","CW","DJ","GA","GG","GH","GL","HT","LB","MU","NC","PG","SC","VC","VG","YT","CV","KM","SZ","VI","GY","BG","BI","CI","CU","EE","GM","HR","HU","LT","LV","MG","MT","NE","PL","SB","SI","SL","TD","TJ","TN","TO","CD","GN","VA","FK","MC","ST","AQ","AX","BL","BQ","BT","BV","CC","CX","EH","ER","FM","FO","GQ","GS","GU","HM","IM","IR","KI","KP","MH","MP","PF","PM","PN","PW","SH","SJ","SY","TF","TK","TM","TV","UM","IC"],"type":"string"},"Customs.Catalog.Common.Pkg.Product.Category":{"enum":["AnimalsPetSupplies","ApparelAccessories","ArtsEntertainment","BabyToddler","BusinessIndustrial","CamerasOptics","Electronics","FoodBeveragesTobacco","Furniture","Hardware","HealthBeauty","HomeGarden","LuggageBags","Mature","Media","OfficeSupplies","ReligiousCeremonial","Software","SportingGoods","ToysGames","VehiclesParts","PerfumeryCosmeticToiletPreparations","SoapPolishCandlesEtc","AlbuminoidalSubstances","ExplosivesEtc","PhotographicCinematographicGoods","MiscellaneousChemicalProducts","Plastics","Rubber","RawHidesAndSkins","ArticlesOfLeather","FurskinsAndArtificialFur","Wood","Cork","ManufacturesOfStrawBasketwareAndWickerwork","PulpOfWoodScrapPaperPaperboard","PaperAndPaperboard","PrintedBooksNewspapers","Silk","WoolAndAnimalHair","Cotton","OtherVegetableTextileFibres","ManMadeFilaments","ManMadeStapleFibres","WaddingSpecialYarnsTwine","CarpetsAndFloorCoverings","SpecialWovenFabrics","IndustrialTextileFabricsAndTextileArticles","KnittedCrochetedFabrics","ApparelClothingKnitted","ApparelClothingNotKnitted","OtherMadeupWornTextileArticles","Footwear","Headgear","UmbrellasAndWalkingSticks","FeathersAndDownArticlesAndArtificialFlowers","ArticlesOfStone","CeramicProducts","GlassAndGlassware","PreciousStonesMetalsAndJewelry","IronAndSteel","ArticlesOfIronSteel","CopperAndArticlesThereof","NickelAndArticlesThereof","AluminumAndArticlesThereof","LeadAndArticlesThereof","ZincAndArticlesThereof","TinAndArticlesThereof","OtherBaseMetalsAndArticlesThereof","ToolsImplementsCutlery","MiscellaneousArticlesOfBaseMetal","NuclearReactorsBoilersMachinery","ElectricalMachinerySoundAndTv","RailwayTramwayLocomotivesRollingStock","VehiclesOtherThanRailwayTramwayRollingStock","AircraftSpacecraft","ShipsBoatsAndFloatingStructures","OpticalPhotographicCinematographicMeasuringMedicalInstruments","ClocksAndWatches","MusicalInstruments","ArmsAndAmmunition","FurnitureAndFurnishings","ToysGamesAndSports","MiscellaneousManufacturedArticles","WorksOfArtAndAntiques","CompleteIndustrialPlant","SpecialCombinedNomenclatureCodes","Digital","ReturnsLabels","DigitalGiftCard"],"type":"string"},"Customs.Catalog.Common.Pkg.Product.Gender":{"enum":["Male","Female","Unisex"],"type":"string"},"Customs.Catalog.Common.Pkg.Product.AgeGroup":{"enum":["Newborn","Infant","Toddler","Kids","Adult","OlderKids","Teen"],"type":"string"},"Customs.Catalog.Common.Pkg.Product.WeightUnit":{"enum":["Lb","Kg"],"type":"string"},"Customs.Catalog.Domain.Pkg.Models.DTO.RetailerPrice":{"type":"object","properties":{"amount":{"type":"number","description":"Amount","format":"double","nullable":true},"currency":{"$ref":"#/components/schemas/Customs.Catalog.Common.Pkg.Product.CurrencyIso"}},"additionalProperties":false,"description":"(Optional *) Price of the product.\n*This field is mandatory if you specify a unitPriceCurrencyIso."},"Customs.Catalog.Common.Pkg.Product.CurrencyIso":{"enum":["ARS","AUD","AZN","BHD","BDT","BBD","BYR","BYN","BZD","BMD","BOB","BRL","BGN","KHR","CAD","CLP","CNY","COP","CRC","HRK","CZK","DKK","DOP","EGP","EUR","GIP","GTQ","HNL","HKD","HUF","INR","IDR","ILS","JMD","JPY","JOD","KZT","KWD","LVL","LTL","MYR","MVR","MXN","MDL","TWD","NZD","NIO","NOK","OMR","PKR","PAB","PYG","PEN","PHP","PLN","GBP","QAR","ROL","RON","RUB","SAR","SGD","ZAR","KRW","LKR","SEK","CHF","THB","TRY","UAH","AED","USD","VEF","VND","RSD","DZD","MOP","NGN","KES","MKD","BAM","ISK","AMD","ALL","GEL"],"type":"string"},"Customs.Catalog.Domain.Pkg.Models.DTO.RestrictionDto":{"type":"object","properties":{"type":{"type":"string","description":"Type of restriction.","nullable":true},"criteria":{"type":"string","description":"Criteria.","nullable":true},"countries":{"type":"array","items":{"type":"string"},"description":"List of countries or \"ALL\" marker restriction to be applied. For example: [\"ALL\"], [\"AU\", \"CH\"]","nullable":true}},"additionalProperties":false,"description":"(Optional) Identifies when a product should be Restricted from Sale in Certain Countries."},"Customs.Catalog.Domain.Pkg.Models.DTO.Error":{"type":"object","properties":{"message":{"type":"string","description":"Error message","nullable":true},"code":{"type":"integer","description":"Error code","format":"int32"}},"additionalProperties":false,"description":"Error information."}}},"paths":{"/api/v2/RetailerCatalog":{"post":{"tags":["RetailerCatalog"],"summary":"Allows a retailer to upload a catalog that will be subject to validation processing.","operationId":"api/v2/RetailerCatalog_POST","requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Customs.Catalog.Domain.Pkg.Models.DTO.RetailerCatalogProduct"}}},"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Customs.Catalog.Domain.Pkg.Models.DTO.RetailerCatalogProduct"}}},"text/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Customs.Catalog.Domain.Pkg.Models.DTO.RetailerCatalogProduct"}}},"application/*+json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Customs.Catalog.Domain.Pkg.Models.DTO.RetailerCatalogProduct"}}}}},"responses":{"202":{"description":"Accepted"},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Customs.Catalog.Domain.Pkg.Models.DTO.Error"}}},"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Customs.Catalog.Domain.Pkg.Models.DTO.Error"}}},"text/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Customs.Catalog.Domain.Pkg.Models.DTO.Error"}}}}}}}}}} ``` # Pricing Import Fetch pricing rules from ESW Pricing Advisor and write fixed prices to Shopify markets. ### 1. ESW Pricing Advisor API Call GET `api/4.0/StandardAdvice/{tenantCode}` to fetch FX rates, uplifts, duties, taxes, and rounding rules for each market. ## GET All available pricing advice for a brand. > This endpoint can be used to retrieve all available pricing advice for a brand. ```json {"openapi":"3.0.4","info":{"title":"Pricing Advisor API","version":"4.0"},"tags":[{"name":"StandardAdvice","description":"Pricing Advisor Controller V4"}],"servers":[{"url":"https://pricing-advisor-api.sandbox.eshopworld.com"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"http","description":"Please insert JWT with Bearer into field","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"PricingAdviceResponse":{"type":"object","properties":{"id":{"type":"string","description":"Gets the identifier.","nullable":true,"readOnly":true},"version":{"type":"string","description":"Gets the version.","nullable":true,"readOnly":true},"countryIso":{"type":"string","description":"Gets the country iso.","nullable":true,"readOnly":true},"lastUpdated":{"type":"string","description":"The UTC date and time that this piece of pricing advice was last updated.","nullable":true,"readOnly":true},"tenantIdentifier":{"type":"string","description":"Gets the tenant identifier.","nullable":true,"readOnly":true},"fxRates":{"type":"array","items":{"$ref":"#/components/schemas/FxRateResponse"},"description":"Gets the fx rates.","nullable":true,"readOnly":true},"categories":{"type":"array","items":{"$ref":"#/components/schemas/CategoryResponse"},"description":"Gets the categories.","nullable":true,"readOnly":true},"merchandisePricingModel":{"$ref":"#/components/schemas/PricingModelResponse"}},"additionalProperties":false,"description":"Pricing Advice Response"},"FxRateResponse":{"type":"object","properties":{"from":{"type":"string","description":"Gets from.","nullable":true,"readOnly":true},"to":{"type":"string","description":"Gets to.","nullable":true,"readOnly":true},"rate":{"type":"number","description":"Gets the rate.","format":"double","readOnly":true}},"additionalProperties":false,"description":"Class FxRateResponse."},"CategoryResponse":{"type":"object","properties":{"id":{"type":"string","description":"Gets or sets the identifier.","nullable":true,"readOnly":true},"estimatedTax":{"type":"number","description":"Gets or sets the estimated tax.","format":"double","readOnly":true},"estimatedFee":{"type":"number","description":"Gets the estimated fee rate.","format":"double","readOnly":true},"estimatedDuty":{"type":"number","description":"Gets or sets the estimated duty.","format":"double","readOnly":true},"retailerAdjustment":{"type":"number","description":"Gets or sets the retailer adjustment.","format":"double","readOnly":true},"roundingConfigurations":{"type":"array","items":{"$ref":"#/components/schemas/RoundingConfigurationResponse"},"description":"Gets or sets the rounding models.","nullable":true,"readOnly":true},"currencyDisplays":{"type":"array","items":{"$ref":"#/components/schemas/CurrencyDisplayResponse"},"description":"Gets or sets the currency displays.","nullable":true,"readOnly":true}},"additionalProperties":false,"description":"Category"},"RoundingConfigurationResponse":{"type":"object","properties":{"currencyIso":{"type":"string","description":"Gets or sets the currency iso.","nullable":true,"readOnly":true},"currencyExponent":{"type":"integer","description":"Gets or sets the currency exponent.","format":"int32","readOnly":true},"direction":{"type":"string","description":"Gets or sets the rounding direction.","nullable":true,"readOnly":true},"model":{"type":"string","description":"Gets or sets the model.","nullable":true,"readOnly":true}},"additionalProperties":false,"description":"Rounding Model"},"CurrencyDisplayResponse":{"type":"object","properties":{"currencyIso":{"type":"string","description":"Gets or sets the currency iso.","nullable":true,"readOnly":true},"currencySymbol":{"type":"string","description":"Gets or sets the currency symbol.","nullable":true,"readOnly":true},"currencyExponent":{"type":"integer","description":"Gets or sets the currency exponent.","format":"int32","readOnly":true},"decimalSeparator":{"type":"string","description":"Gets or sets the decimal separator.","nullable":true,"readOnly":true},"thousandSeparator":{"type":"string","description":"Gets or sets the thousand separator.","nullable":true,"readOnly":true},"showTrailingZeros":{"type":"boolean","description":"Gets or sets a value indicating whether [show trailing zeros].","readOnly":true},"configurationString":{"type":"string","description":"Gets or sets the configuration string.","nullable":true,"readOnly":true}},"additionalProperties":false,"description":"Currency Display"},"PricingModelResponse":{"type":"object","properties":{"id":{"type":"string","description":"The input models ID.","nullable":true,"readOnly":true},"applicableRates":{"type":"array","items":{"type":"string"},"description":"The list of rates that are applicable to estimated prices based on the currency input model.","nullable":true,"readOnly":true}},"additionalProperties":false,"description":"Represents a pricing model response."},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/api/4.0/StandardAdvice/{tenantCode}":{"get":{"tags":["StandardAdvice"],"summary":"GET All available pricing advice for a brand.","description":"This endpoint can be used to retrieve all available pricing advice for a brand.","operationId":"GetAll","parameters":[{"name":"tenantCode","in":"path","description":"The tenant identifier.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"text/plain":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PricingAdviceResponse"}}},"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PricingAdviceResponse"}}},"text/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PricingAdviceResponse"}}}}},"400":{"description":"Bad Request","content":{"text/plain":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}},"text/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden"}}}}}} ``` ### 2. Shopify Admin API (GraphQL) Upsert the calculated prices as fixed prices in Shopify. Use Shopify price lists and the GraphQL mutation: #### [priceListFixedPricesAdd](https://shopify.dev/docs/api/admin-graphql/latest/mutations/priceListFixedPricesAdd) Implementation notes: * Batch updates to stay within rate limits. * Make writes idempotent. * Log failures with enough data to replay. ### Shopify reference links {% tabs %} {% tab title="Fixed prices by country/market" %} [Product prices by country (Shopify Help)](https://help.shopify.com/en/manual/international/pricing/product-prices-by-country#set-fixed-product-prices-using-the-shopify-api) {% endtab %} {% tab title="Fixed prices for specific variants" %} [Set fixed prices for specific variants (Shopify Dev)](https://shopify.dev/docs/apps/build/markets/build-catalog#step-3-set-fixed-prices-for-specific-product-variants) {% endtab %} {% endtabs %} # Order Ingestion ### 1. Shopify order webhook Subscribe to Shopify’s order creation webhook.
Cover image Cover image (dark)
orders/create /files/l7pL6vchwKVIHlSWnsQZ /files/Zn9WWvNhKVBMLfohh8Wa https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook#event-topics-orders-create
### 2. ESW Create Order API Call ESW `CreateOrder` to register the Shopify order in ESW. ## POST /v2/{tenantCode}/Order > Creates an order. ```json {"openapi":"3.0.1","info":{"title":"Order Transaction API","version":"v2"},"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Please insert JWT with Bearer into field","name":"Authorization","in":"header"}},"schemas":{"OrderCreate":{"required":["actionedBy","brandOrderReference","contactDetails","deliveryCountryIso","deliveryOption","lineItems","orderType","retailerCurrencyIso","shopperCurrencyIso","shopperExperience","transactionDateTime","transactionReference"],"type":"object","properties":{"brandOrderReference":{"minLength":1,"type":"string","description":"The Brand's order number."},"weight":{"$ref":"#/components/schemas/WeightInfo"},"orderType":{"$ref":"#/components/schemas/OrderType"},"parentBrandOrderReference":{"type":"string","description":"The parent order number.","nullable":true},"externalOrderId":{"type":"string","description":"ExternalOrderId.","nullable":true},"transactionReference":{"type":"string","description":"Unique reference number of the transaction","format":"uuid"},"transactionDateTime":{"type":"string","description":"The date/time logged by the retailer for the creation of the order in UTC.","format":"date-time"},"actionedBy":{"$ref":"#/components/schemas/ActionedBy"},"actionedByUser":{"type":"string","description":"Identifier for the person who initiated the action, for example, John Smith or johnsmith@test.com.","nullable":true},"shopperCurrencyIso":{"minLength":1,"type":"string","description":"ISO 4217 format three-letter identifier for the shopper currency."},"retailerCurrencyIso":{"minLength":1,"type":"string","description":"ISO 4217 format three-letter identifier for the retailer's currency."},"deliveryCountryIso":{"minLength":1,"type":"string","description":"ISO 3166 format two-letter country identifier for the delivery country."},"shopperExperience":{"$ref":"#/components/schemas/ShopperExperience"},"contactDetails":{"type":"array","items":{"$ref":"#/components/schemas/ContactDetail"},"description":"Shopper’s delivery or payment contact details. If multiple contactDetails are passed, they will be applied first-to-last."},"lineItems":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemToCreate"},"description":"Attributes that describe the items in the cart. There can be multiple cart items. A minimum of one cart item is required."},"deliveryOption":{"$ref":"#/components/schemas/DeliveryOptionCreate"},"retailerInvoice":{"$ref":"#/components/schemas/RetailerInvoice"},"payment":{"$ref":"#/components/schemas/Payment"},"originDetails":{"$ref":"#/components/schemas/OriginDetails"},"metadataItems":{"type":"array","items":{"$ref":"#/components/schemas/MetadataItem"},"description":"Key-value pairs used for passing additional details. Use of metadataItems must be agreed with eShopWorld. This applies to all metadataItems within this API.","nullable":true},"channelType":{"type":"string","description":"Channel Type","nullable":true}},"additionalProperties":false,"description":"Order create request"},"WeightInfo":{"type":"object","properties":{"weightTotal":{"type":"number","description":"Total weight of the order.","format":"double"},"weightUnit":{"$ref":"#/components/schemas/WeightUnit"}},"additionalProperties":false,"description":"(Required) Attributes that describe the package weight data."},"WeightUnit":{"enum":["KG","LB"],"type":"string","description":"Unit of measurement for the items in the package. 0 indicates KG and 1 indicates LB."},"OrderType":{"enum":["Offline","Checkout","NonCheckoutEcommerce"],"type":"string","description":"OrderType"},"ActionedBy":{"enum":["Retailer","Shopper","EShopWorld","ThirdParty"],"type":"string","description":"To define Who initiated the request"},"ShopperExperience":{"required":["shopperCultureLanguageIso"],"type":"object","properties":{"shopperCultureLanguageIso":{"minLength":1,"type":"string","description":"Preferred language and culture experience for the shopper in the ISO 639-1 and ISO 3166 format."},"registeredProfileId":{"type":"string","description":"Customer profile Id or number","nullable":true}},"additionalProperties":false,"description":"Shopper Experience"},"ContactDetail":{"required":["address1","city","contactDetailsType","country","email","firstName","lastName","telephone"],"type":"object","properties":{"contactDetailsType":{"$ref":"#/components/schemas/ContactDetailsType"},"nickName":{"type":"string","description":"Nickname or identifier for the contact information.","nullable":true},"addressId":{"type":"string","description":"Address Identifier","nullable":true},"firstName":{"minLength":1,"type":"string","description":"First name of the address."},"lastName":{"minLength":1,"type":"string","description":"Last name of the address."},"address1":{"minLength":1,"type":"string","description":"Address line 1 of the address."},"address2":{"type":"string","description":"Address line 2 of the address.","nullable":true},"address3":{"type":"string","description":"Address line 3 of the address.","nullable":true},"city":{"minLength":1,"type":"string","description":"City of the address."},"postalCode":{"type":"string","description":"Postal code or zip code of the address.","nullable":true},"region":{"type":"string","description":"Region, province, state, or county of the address. ISO can be provided, if available.","nullable":true},"country":{"minLength":1,"type":"string","description":"ISO 3166 two-letter country code of the address."},"email":{"minLength":1,"type":"string","description":"Email address."},"telephone":{"minLength":1,"type":"string","description":"Phone number."},"gender":{"$ref":"#/components/schemas/Gender"},"poBox":{"type":"string","description":"Postal order box of the address.","nullable":true}},"additionalProperties":false,"description":"Contact Details"},"ContactDetailsType":{"enum":["IsDelivery","IsPayment","IsDeliveryAndPayment","IsStoreDelivery"],"type":"string","description":"ContactDetailsType"},"Gender":{"enum":["None","Male","Female","Unisex"],"type":"string","description":"Gender"},"OrderItemToCreate":{"required":["lineItemId","product","quantity"],"type":"object","properties":{"lineItemId":{"minLength":1,"type":"string","description":"Item sequence or line item ID."},"quantity":{"type":"integer","description":"Number of product pieces. Matches the length of the articles property","format":"int32"},"estimatedDeliveryDateFromRetailer":{"type":"string","description":"Estimated delivery date of the cart items in the ISO 8601 format. This date is for the first leg of the journey.","format":"date-time","nullable":true},"product":{"$ref":"#/components/schemas/ProductCreate"},"metadataItems":{"type":"array","items":{"$ref":"#/components/schemas/MetadataItem"},"description":"Key-value pairs used for passing additional details. Use of metadataItems must be agreed with eShopWorld. This applies to all metadataItems within this API.","nullable":true}},"additionalProperties":false,"description":"Cart Items"},"ProductCreate":{"required":["description","productCode","productUnitPriceInfo","title"],"type":"object","properties":{"title":{"minLength":1,"type":"string","description":"Localized title of the product. If no title is provided, eShopWorld may use the description from the Product Catalog."},"description":{"minLength":1,"type":"string","description":"Localized description of the product. If no description is provided, eShopWorld may use the description from the Product Catalog."},"customsDescription":{"type":"string","description":"Localized description of the product. If no description is provided, eShopWorld may use the description from the Product Catalog.","nullable":true},"productCode":{"minLength":1,"type":"string","description":"Unique identification code or SKU for the product."},"hsCode":{"type":"string","description":"HsCode.","nullable":true},"countryOfOriginIso":{"type":"string","description":"CountryOfOrigin.","nullable":true},"imageUrl":{"type":"string","description":"Thumbnail image URL of the product. The image size must be less than or equal to 20 KB and the image must be retina-ready.","nullable":true},"color":{"type":"string","description":"Color of the item.","nullable":true},"size":{"type":"string","description":"Size of the item.","nullable":true},"productUnitPriceInfo":{"$ref":"#/components/schemas/PriceInfo"},"wholesalePriceInfo":{"$ref":"#/components/schemas/PriceInfo"},"weightInfo":{"$ref":"#/components/schemas/WeightInfo"},"isReturnProhibited":{"type":"boolean","description":"Indicates whether the item is returnable or not under the regular return policy. The values are True or False.","nullable":true},"isCustomized":{"type":"boolean","description":"Indicates whether the item is customized or not. The values are True or False."}},"additionalProperties":false,"description":"Product"},"PriceInfo":{"type":"object","properties":{"price":{"$ref":"#/components/schemas/Money"}},"additionalProperties":false,"description":"Price Info"},"Money":{"type":"object","properties":{"currency":{"type":"string","description":"Currency three-letter identifier (in the ISO 4217 format).","nullable":true},"amount":{"type":"string","description":"The amount of the currency.","nullable":true}},"additionalProperties":false,"description":"Money"},"MetadataItem":{"type":"object","properties":{"name":{"type":"string","description":"Metadata name/key.","nullable":true},"value":{"type":"string","description":"Metadata value.","nullable":true}},"additionalProperties":false,"description":"Key and value pairs to pass metadata information."},"DeliveryOptionCreate":{"required":["eshopDeliveryOptionCode","priceInfo"],"type":"object","properties":{"priceInfo":{"$ref":"#/components/schemas/PriceInfo"},"eshopDeliveryOptionCode":{"$ref":"#/components/schemas/ServiceLevel"},"estimatedDeliveryDateToShopper":{"type":"string","description":"Estimated delivery date of the items in the cart in the ISO 8601 format for the non-eShopWorld delivery option. This date is the expected final delivery date to the shopper.","format":"date-time","nullable":true},"vatRate":{"type":"number","description":"Vat rate","format":"double"}},"additionalProperties":false,"description":"Delivery Option"},"ServiceLevel":{"enum":["DEFAULT","POST","EXP1","EXP2","RussiaExpress","Standard","PUDO"],"type":"string","description":"Service Levels."},"RetailerInvoice":{"type":"object","properties":{"number":{"type":"string","description":"RetailerInvoice number","nullable":true},"date":{"type":"string","description":"RetailerInvoice Date in the yyyy-MM-dd format","nullable":true}},"additionalProperties":false,"description":"RetailerInvoice details"},"Payment":{"type":"object","properties":{"method":{"type":"string","description":"Payment method used","nullable":true},"last4Digits":{"type":"string","description":"Last 4 digits of the payment card","nullable":true},"paymentAttemptRef":{"type":"string","description":"Payment attempt reference","format":"uuid","nullable":true},"priceInfo":{"$ref":"#/components/schemas/PriceInfo"},"deliveryPriceInfo":{"$ref":"#/components/schemas/PriceInfo"},"retailerPriceInfo":{"$ref":"#/components/schemas/PriceInfo"},"retailerDeliveryPriceInfo":{"$ref":"#/components/schemas/PriceInfo"},"paymentStatus":{"type":"string","description":"Payment Status","nullable":true},"merchantPaymentId":{"type":"string","description":"Merchant Payment Id","nullable":true},"paymentTime":{"type":"string","description":"The time when the payment was taken","format":"date-time"},"preAuthExpiryTime":{"type":"string","description":"The datetime when we can kick off the capture process for the payment","format":"date-time"},"authResult":{"type":"string","description":"Auth result of the payment","nullable":true}},"additionalProperties":false,"description":"Payment details"},"OriginDetails":{"required":["address1","city","country","email","originType"],"type":"object","properties":{"originType":{"$ref":"#/components/schemas/OriginType"},"firstName":{"type":"string","description":"First name of the address.","nullable":true},"lastName":{"type":"string","description":"Last name of the address.","nullable":true},"telephone":{"type":"string","description":"Phone number.","nullable":true},"nickName":{"type":"string","description":"Nickname or identifier for the contact information.","nullable":true},"addressId":{"type":"string","description":"Address Identifier","nullable":true},"address1":{"minLength":1,"type":"string","description":"Address line 1 of the address."},"address2":{"type":"string","description":"Address line 2 of the address.","nullable":true},"address3":{"type":"string","description":"Address line 3 of the address.","nullable":true},"city":{"minLength":1,"type":"string","description":"City of the address."},"postalCode":{"type":"string","description":"Postal code or zip code of the address.","nullable":true},"region":{"type":"string","description":"Region, province, state, or county of the address. ISO can be provided, if available.","nullable":true},"country":{"minLength":1,"type":"string","description":"ISO 3166 two-letter country code of the address."},"email":{"minLength":1,"type":"string","description":"Email address."},"gender":{"$ref":"#/components/schemas/Gender"},"poBox":{"type":"string","description":"Postal order box of the address.","nullable":true}},"additionalProperties":false,"description":"Origin Details"},"OriginType":{"enum":["None","Store"],"type":"string","description":"Payment methods"},"OrderTransactionApiResponse":{"type":"object","properties":{"transactionReference":{"type":"string","description":"Unique reference number of the transaction.\r\nIf the retailer sends this data, eSW will honor it. If the retailer does not send this data, eSW will generate the GUID for the transaction.","format":"uuid"}},"additionalProperties":false,"description":"Response from Order API"},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error Identifier code","format":"int32"},"message":{"type":"string","description":"Error Message","nullable":true}},"additionalProperties":false,"description":"Error Response"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/v2/{tenantCode}/Order":{"post":{"tags":["Order"],"summary":"Creates an order.","operationId":"OrderCreate","parameters":[{"name":"tenantCode","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderCreate"}}}},"responses":{"202":{"description":"The request is accepted, but not processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderTransactionApiResponse"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"401":{"description":"The request is unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"The request is forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal server error"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}} ``` # Address Update Capture post-purchase shipping address changes in Shopify and sync them to ESW. ### 1. Subscribe to the Order Updates Webhook in Shopify Listen for the `orders/updated` webhook to track shipping address updates made to an order.
Cover image Cover image (dark)

orders/updated
/files/8uBoR4UpqWLFCtycVZoX /files/MOVOzmFm08yF5bliCROB https://shopify.dev/docs/api/admin-rest/2025-04/resources/webhook#event-topics-orders-updated
*** ### 2. ESW API Call Sync shipping address changes to ESW using the Update Contact Details API. ## Update Order Contact details > Method to update Order Address info by using brand order reference ```json {"openapi":"3.0.1","info":{"title":"Order Transaction API","version":"v2"},"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Please insert JWT with Bearer into field","name":"Authorization","in":"header"}},"schemas":{"UpdateOrderContacts":{"required":["actionedBy","contactDetails","transactionDateTime","transactionReference"],"type":"object","properties":{"transactionReference":{"type":"string","description":"Unique reference number of the transaction","format":"uuid"},"transactionDateTime":{"type":"string","description":"The date/time logged by the retailer for the creation of the order in UTC.","format":"date-time"},"actionedBy":{"$ref":"#/components/schemas/ActionedBy"},"actionedByUser":{"type":"string","description":"Identifier for the person who initiated the action, for example, John Smith or johnsmith@test.com.","nullable":true},"contactDetails":{"$ref":"#/components/schemas/UpdateContactDetail"}},"additionalProperties":false,"description":"Update Contact details like address info."},"ActionedBy":{"enum":["Retailer","Shopper","EShopWorld","ThirdParty"],"type":"string","description":"To define Who initiated the request"},"UpdateContactDetail":{"required":["address1","city","contactDetailsType","email","postalCode","telephone"],"type":"object","properties":{"contactDetailsType":{"$ref":"#/components/schemas/UpdateContactDetailsType"},"address1":{"minLength":1,"type":"string","description":"Address line 1 of the address."},"address2":{"type":"string","description":"Address line 2 of the address.","nullable":true},"address3":{"type":"string","description":"Address line 3 of the address.","nullable":true},"city":{"minLength":1,"type":"string","description":"City of the address."},"postalCode":{"minLength":1,"type":"string","description":"Postal code or zip code of the address."},"region":{"type":"string","description":"Region, province, state, or county of the address. ISO can be provided, if available.","nullable":true},"email":{"minLength":1,"type":"string","description":"Email address."},"telephone":{"minLength":1,"type":"string","description":"Phone number."}},"additionalProperties":false,"description":"Update Contact Details"},"UpdateContactDetailsType":{"enum":["IsDelivery"],"type":"string","description":"ContactDetailsType"},"OrderTransactionApiResponse":{"type":"object","properties":{"transactionReference":{"type":"string","description":"Unique reference number of the transaction.\r\nIf the retailer sends this data, eSW will honor it. If the retailer does not send this data, eSW will generate the GUID for the transaction.","format":"uuid"}},"additionalProperties":false,"description":"Response from Order API"},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error Identifier code","format":"int32"},"message":{"type":"string","description":"Error Message","nullable":true}},"additionalProperties":false,"description":"Error Response"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/v2/{tenantCode}/Order/{brandOrderReference}/ContactDetails":{"put":{"tags":["Order"],"summary":"Update Order Contact details","description":"Method to update Order Address info by using brand order reference","operationId":"ContactDetails","parameters":[{"name":"brandOrderReference","in":"path","description":"","required":true,"schema":{"type":"string"}},{"name":"tenantCode","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateOrderContacts"}}}},"responses":{"202":{"description":"The request is accepted, but not processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderTransactionApiResponse"}}}},"400":{"description":"The request is not valid","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal server error"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}} ``` # Fulfilment and Shipping Sync ESW shipment and tracking updates back into Shopify fulfillments. ESW drives fulfillment execution. Use ESW shipping events to create Shopify fulfillments. ### 1. ESW `PackageEvent` Listen for ESW `PackageEvent` messages. Use them to capture: * Tracking number(s) * Carrier details * Shipped line items and quantities * A stable package/event identifier for deduplication
Cover image Cover image (dark)
ESW event
PackageEvent /files/l7pL6vchwKVIHlSWnsQZ /files/Zn9WWvNhKVBMLfohh8Wa
{% hint style="info" %} Treat ESW events as at-least-once delivery. Deduplicate and make Shopify writes idempotent. {% endhint %} ### 2. Shopify Admin API (GraphQL) Create the Shopify fulfillment for the items shipped in the package. #### Shopify reference [fulfillmentCreateV2](https://shopify.dev/docs/api/admin-graphql/latest/mutations/fulfillmentCreateV2) Implementation notes: * Create one Shopify fulfillment per ESW package when possible. * Create partial fulfillments when the package ships a subset of items. * Store the Shopify fulfillment id against the ESW package id. * Update tracking info consistently for replays and retries. # Cancellations Keep cancellation state in sync between Shopify and ESW (full and item-level). ### A. Order-Level Cancellations #### 1. Shopify to ESW When an order is cancelled in Shopify, the cancellation is sent to ESW through the **Cancel Order API**, ensuring both platforms remain synchronized. ## Cancels the entire order, that is, all line items in the order are cancelled. > Method to cancel an order by brand order reference ```json {"openapi":"3.0.1","info":{"title":"Order Transaction API","version":"v2"},"security":[{"Bearer":[]}],"components":{"securitySchemes":{"Bearer":{"type":"apiKey","description":"Please insert JWT with Bearer into field","name":"Authorization","in":"header"}},"schemas":{"OrderActivityRequest":{"required":["actionedBy","activityStatus","reasonCode","transactionDateTime","transactionReference"],"type":"object","properties":{"activityStatus":{"$ref":"#/components/schemas/ActivityStatus"},"reasonCode":{"$ref":"#/components/schemas/OrderActivityReasonCode"},"settlementReference":{"type":"string","description":"Unique reference number of the settlement transaction. When the Retailer is using “self-billing” Settlement model, this field should be sent.","nullable":true},"transactionReference":{"type":"string","description":"Unique reference number of the transaction","format":"uuid"},"transactionDateTime":{"type":"string","description":"The date/time logged by the retailer for the creation of the order transaction in UTC.","format":"date-time"},"actionedBy":{"$ref":"#/components/schemas/ActionedBy"},"actionedByUser":{"type":"string","description":"Identifier for the person who initiated the action, for example, John Smith or johnsmith@test.com.","nullable":true}},"additionalProperties":false,"description":"OrderActivityRequest"},"ActivityStatus":{"enum":["Cancel","Fulfil"],"type":"string","description":"ActivityStatus"},"OrderActivityReasonCode":{"enum":["ShopperCancel","RetailerCancel","Fraud"],"type":"string","description":"Order Activity Reason Code"},"ActionedBy":{"enum":["Retailer","Shopper","EShopWorld","ThirdParty"],"type":"string","description":"To define Who initiated the request"},"OrderTransactionApiResponse":{"type":"object","properties":{"transactionReference":{"type":"string","description":"Unique reference number of the transaction.\r\nIf the retailer sends this data, eSW will honor it. If the retailer does not send this data, eSW will generate the GUID for the transaction.","format":"uuid"}},"additionalProperties":false,"description":"Response from Order API"},"Error":{"type":"object","properties":{"code":{"type":"integer","description":"Error Identifier code","format":"int32"},"message":{"type":"string","description":"Error Message","nullable":true}},"additionalProperties":false,"description":"Error Response"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}},"paths":{"/v2/{tenantCode}/Order/{brandOrderReference}/OrderActivity":{"post":{"tags":["Order"],"summary":"Cancels the entire order, that is, all line items in the order are cancelled.","description":"Method to cancel an order by brand order reference","operationId":"OrderActivity","parameters":[{"name":"brandOrderReference","in":"path","description":"Retailer's unique reference number for the order","required":true,"schema":{"type":"string"}},{"name":"tenantCode","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Order Activity Details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderActivityRequest"}}}},"responses":{"202":{"description":"The request is accepted, but not processed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderTransactionApiResponse"}}}},"400":{"description":"The request is invalid","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}}}},"401":{"description":"The request is unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"403":{"description":"The request is forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"404":{"description":"No order found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}},"500":{"description":"Internal server error"},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}}} ``` #### 2. ESW to Shopify When ESW cancels an order, the update is communicated to Shopify using the GraphQL `orderCancel` mutation, so both systems display the same order status. ### B. Item-Level Cancellations #### 1. Shopify Item Cancellations Cancelling specific items in Shopify triggers the ESW Item Cancel API, updating ESW. #### 2. ESW Item Cancellations When ESW cancels individual items, Shopify is updated using the `refundCreate` API. # SFCC Integration Start here for ESW Salesforce Commerce Cloud integration guides, including installation, setup, and onboarding resources Use the ESW SFCC cartridge to connect Salesforce Commerce Cloud with ESW services. This integration supports localized pricing, international checkout, order sync, and storefront localization across supported markets.
### What this integration includes Use the SFCC cartridge to add core ESW capabilities to your storefront: * localized pricing with fixed, calculated, or hybrid models * checkout routing for ESW-supported and native countries * order, shipping, catalog, and returns integrations For example, a shopper in Sweden can see localized pricing in `SEK`, enter ESW Checkout, and have the confirmed order synced back into SFCC. A shopper in a non-supported market stays on the native SFCC flow with native pricing and checkout. {% tabs %} {% tab title="Choose your starting point" %} Start with the path that matches your implementation stage: * New implementation — [Get Started](/salesforce-commerce-cloud/salesforce-commerce-cloud/get-started) * Cartridge install — [Cartridge Installation](/salesforce-commerce-cloud/salesforce-commerce-cloud/cartridge-installation) * Storefront customization — [Cartridge Setup](/salesforce-commerce-cloud/salesforce-commerce-cloud/cartridge-setup) {% endtab %} {% tab title="Supported storefront architectures" %} Choose the guide for your storefront architecture: * [Storefront Reference Architecture](/salesforce-commerce-cloud/salesforce-commerce-cloud/cartridge-installation/storefront-reference-architecture) * [Composable Storefront](/salesforce-commerce-cloud/salesforce-commerce-cloud/cartridge-installation/composable-storefront) * [Headless (OCAPI) Architecture](/salesforce-commerce-cloud/salesforce-commerce-cloud/cartridge-installation/headless-ocapi-architecture) If you use SiteGenesis, follow the [SiteGenesis installation guide](/salesforce-commerce-cloud/salesforce-commerce-cloud/cartridge-installation/sitegenesis). {% endtab %} {% tab title="Common implementation areas" %} Use these sections as your main references during implementation: * [Pricing](/salesforce-commerce-cloud/salesforce-commerce-cloud/pricing) for localized price construction, price books, FX, and rounding * [Checkout Integration](/salesforce-commerce-cloud/salesforce-commerce-cloud/checkout-integration) for checkout routing, metadata, payment, and order confirmation * [Catalog and Product Integration](/salesforce-commerce-cloud/salesforce-commerce-cloud/catalog-and-product-integration) for catalog feeds, restrictions, and localization Use [Shipping and Fulfilment](/salesforce-commerce-cloud/salesforce-commerce-cloud/shipping-and-fulfilment) for shipping methods, packages, and multi-origin flows. Use [Order Management](/salesforce-commerce-cloud/salesforce-commerce-cloud/order-management) and [Returns and Refunds](/salesforce-commerce-cloud/salesforce-commerce-cloud/returns-and-refunds) for post-checkout operations. {% endtab %} {% endtabs %} ### Sample implementation flow {% stepper %} {% step %} ### Install the cartridge Import metadata, services, and jobs. Add the cartridge to your active code version. {% endstep %} {% step %} ### Configure Business Manager Set site preferences, services, content slots, and payment methods. Enable the ESW module and run initial data population jobs. {% endstep %} {% step %} ### Apply storefront integration Implement the setup for your architecture. Then configure pricing, checkout, shipping, and order flows. {% endstep %} {% step %} ### Validate before launch Recommended validation path. Before launch, review these pages: * [Testing Guide](/salesforce-commerce-cloud/salesforce-commerce-cloud/testing-and-launch/testing-guide) * [Go-Live Readiness](/salesforce-commerce-cloud/salesforce-commerce-cloud/testing-and-launch/going-live/go-live-readiness) * [Checklist](/salesforce-commerce-cloud/salesforce-commerce-cloud/testing-and-launch/going-live/checklist) {% endstep %} {% endstepper %} # Get Started Install and configure the ESW cartridge in Salesforce Commerce Cloud (SFCC), including prerequisites and initial setup steps This guide provides step-by-step instructions for installing and configuring the **ESW cartridge** in **Salesforce Commerce Cloud (SFCC)**. The ESW cartridge enables SFCC to integrate with ESW’s services, including: * Localized pricing * Checkout integration * Payment integration ### Prerequisites {% hint style="warning" %} SFCC sandbox instances include preconfigured sites—such as **RefArch**, **RefArch Global**, **SiteGenesis**, and **SiteGenesis EU**—in their native configurations. These serve as the foundation for building a custom eCommerce experience. This documentation is based on the **RefArch** architecture. {% endhint %} Before you begin the installation, ensure you have the following: * **Access to an SFCC instance** ( **SIG** or **PIG**) with SFCC Business Manager. * **API credentials** provided by **ESW**. # Prerequisites Installing and configuring the ESW cartridge in Salesforce Commerce Cloud (SFCC)
The ESW cartridge enables SFCC to integrate with ESW’s services, including: * Localized pricing * Checkout integration * Payment integration ### Prerequisites {% hint style="info" icon="salesforce" %} SFCC sandbox instances include preconfigured sites—such as **RefArch**, **RefArch Global**, **SiteGenesis**, and **SiteGenesis EU**—in their native configurations. These serve as the foundation for building a custom eCommerce experience. This documentation is based on the **RefArch** architecture. {% endhint %} Before you begin the installation, ensure you have the following: * **Access to an SFCC instance** (**SIG** or **PIG**) with SFCC Business Manager. * **API credentials** provided by **ESW**. # Download ESW Cartridge You can download the ESW cartridge package from the AppExchange listing {% embed url="" %} Download Cartridge {% endembed %} ### Package contents The package includes: * Cartridges for **SFRA**, **SiteGenesis**, **PWA**, and **Headless** * Metadata files * Job and service configuration files ### Installation Copy the relevant cartridge folders into your **local development environment** to begin setup. # Import Metadata Import essential metadata files into Salesforce Commerce Cloud (SFCC) Before using the ESW cartridge functionality, you must import essential metadata files into Salesforce Commerce Cloud (SFCC). These files configure custom objects, services, jobs, and site preferences required for proper cartridge operation. ### ESW Metadata Files | Metadata File Name | Path | Description | | :--------------------------: | :-----------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------: | | `customobjects.xml` | `/link_eshopworld/Metadata/meta/` | ESW custom objects | | `customobjects_pwa.xml` | `/link_eshopworld/Metadata/meta/` | ESW additional custom objects for PWA | | `systemobjects.xml` | `/link_eshopworld/Metadata/meta/` | ESW system objects extensions | | `systemobjects_headless.xml` | `/link_eshopworld/Metadata/meta/` | ESW additional system objects for Headless | | `systemobjects_pwa.xml` | `/link_eshopworld/Metadata/meta/` | ESW additional system objects for PWA | | `services.xml` | `/link_eshopworld/Metadata/` | ESW services | | `jobs.xml` | `/link_eshopworld/Metadata/` | ESW jobs | | `content-assets.xml` |
/link\_eshopworld/Metadata/sites/SiteGenesis
or
/link\_eshopworld/Metadata/sites/RefArch
| ESW content assets | | `payment-methods.xml` |
/link\_eshopworld/Metadata/sites/SiteGenesis
or
/link\_eshopworld/Metadata/sites/RefArch
| ESW payment methods | | `slots.xml` |
/link\_eshopworld/Metadata/sites/SiteGenesis
or
/link\_eshopworld/Metadata/sites/RefArch
| ESW slots | ### Metadata Import Steps To fully enable ESW cartridge functionality, the following metadata files must be imported into SFCC Business Manager using MERGE mode. This ensures existing configurations are preserved while new ones are added. {% stepper %} {% step %} #### Import customobjects.xml, systemobjects.xml, systemobjects\_headless.xml files Navigate to **Administration > Site Development > Import & Export** * Import in **MERGE** mode: * `customobjects.xml` * `systemobjects.xml` * `systemobjects_headless.xml` ![Image](/files/48029d5bb4f482e67d7b80b90cbaf1d92121b488) {% endstep %} {% step %} #### Import services.xml, jobs.xml files Navigate to **Administration > Site Development > Import & Export** * Import in **MERGE** mode: * `services.xml` * `jobs.xml` {% endstep %} {% step %} #### Import content-assets.xml file Navigate to **Administration > Site Development > Import & Export** * Import in **MERGE** mode: * `content-assets.xml` {% endstep %} {% step %} #### Import payment-methods.xml file Navigate to **Administration > Site Development > Import & Export** * Import in **MERGE** mode: * `payment-methods.xml` {% endstep %} {% step %} #### Import slots.xml file Navigate to **Administration > Site Development > Import & Export** * Import in **MERGE** mode: * `slots.xml` {% endstep %} {% endstepper %} # Upload metadata XML files How to import metadata using the Business Manager ### Import Metadata **Metadata** includes both system and custom objects required to enable the ESW integration. {% tabs %} {% tab title="System objects" %} System objects are core SFCC components that define standard platform functionalities. They include the essential data structures required for the site’s basic operation, such as: * Countries * Currencies * Shipping methods {% endtab %} {% tab title="Custom Objects" %} Custom objects enable business-specific configurations that extend the capabilities of SFCC. They provide flexibility to support additional capabilities, such as: * Tenant credentials * Pricing Advisor settings {% endtab %} {% endtabs %} Together, these objects form the **metadata**, which defines the operational framework of SFCC. ### Steps to import metadata files Follow these steps to import the metadata files included in the ESW package: {% stepper %} {% step %} #### Navigate to Import & Export Navigate to **Administration → Site Development → Import & Export** {% endstep %} {% step %} #### Upload Metadata Files Upload the **metadata XML files** included in the **ESW package**.
{% endstep %} {% endstepper %} # Import Jobs and Services How to import job and service configuration files using the Business Manager **Jobs** and **services** enable automation and real-time communication between SFCC and ESW. * **Jobs** – Execute scheduled tasks such as price updates or order exports. * **Services** – Handle API interactions to ensure real-time data exchange between SFCC and ESW. These components work together to automate processes like order processing, data synchronization, and pricing updates. ### Steps to import Follow these steps to import the job and service configuration files included in the ESW package: {% stepper %} {% step %} #### Navigate to Import & Export Navigate to **Administration → Operations → Import & Export** {% endstep %} {% step %} #### Upload ESW Package Files * From the **ESW package**, upload: * **Jobs XML file** * **Services XML files** The jobs file initializes automated tasks that maintain key aspects of the system, such as order processing and data synchronization. Similarly, services enable SFCC to communicate with external systems in real time.
{% endstep %} {% endstepper %} # Configure Content Slots and Payment Methods How to configure content slots and payment methods ### Configure Content Slots To enable **payment processing** and **layout customization**, you must import payment methods and content slots. {% stepper %} {% step %} #### Navigate to Import & Export Navigate to **Merchant Tools → Online Marketing → Import & Export** {% endstep %} {% step %} #### Upload Content Slots File * Upload the **content slots file** from the `/Sites` directory of the **ESW package**. **Content slots** define configurable areas in the storefront that can display promotional content, or other dynamic elements. Importing content slots ensures ESW marketing and UI components are available for storefront customization.
{% endstep %} {% endstepper %} ### Import Payment Methods Follow these steps to import the ESW-supported payment methods. {% stepper %} {% step %} #### Navigate to Import & Export Navigate to **Merchant Tools → Ordering → Import & Export**
{% endstep %} {% step %} #### Import Payment Methods * Go to **Payment Methods** and click **Import**. * Upload the **ESW-supported payment methods** file to enable ESW transaction processing. {% endstep %} {% step %} #### Verify Payment Method Setup * Upon successful import: * A new payment method **`ESW_PAYMENT`** is created. * This payment method is associated with the **`BASIC_CREDIT`** processor.
Importing ESW-supported payment methods ensures compatibility with ESW’s checkout and payment processing. {% endstep %} {% endstepper %} # Configure ESW Services How to configure the ESW services ## ESWOAuthServices The **EswOAuthService** is required for authentication across all ESW services, including critical endpoints such as the **Checkout** service. Configuration ensures secure and seamless integration between SFCC and ESW. Follow these steps to configure **ESW Price Feed Service and Configure Checkout Service**
Section Link Cover image
Configure ESW Price Feed Service /spaces/GUPR15ARSjXiz9aZEsDU/pages/70060436547c143fb5e0e1537058e400b5a0a6fe#configure-esw-price-feed-service /files/y2WjaH9yHDGIj0rHr2Ts
Configure Checkout Service /spaces/GUPR15ARSjXiz9aZEsDU/pages/70060436547c143fb5e0e1537058e400b5a0a6fe#configure-checkout-service /files/dZyNQDGvjUecv5SzCVl1
#### Configure ESW Price Feed Service {% stepper %} {% step %} #### Access Services Navigate to **Administration → Operations → Services** *** {% endstep %} {% step %} #### Configure `EswPriceFeedCredentials` Configure the `EswPriceFeedCredentials` with the provided API URL, with support for both `V3` and `V4` versions.
{% endstep %} {% endstepper %} *** ### Configure Checkout Service {% stepper %} {% step %} #### Access Services Navigate to **Administration → Operations → Services** *** {% endstep %} {% step %} #### Configure Checkout Service Select `EswCheckoutV3Service.SFRA`
{% endstep %} {% endstepper %} ### Checkout configuration Ensure that the following URL settings are set under **ESW URL Expansion Pair** in the ESW Checkout Configuration: * `ContinueShoppingUrl|Home-Show` * `BaseUrl|EShopWorld-Home` * `BackToCartUrl|Cart-Show` # Add Cartridge to SFCC How to add the ESW cartridge to SFCC ### Adding the Cartridge to SFCC Integrate the [downloaded ESW cartridge](/salesforce-commerce-cloud/salesforce-commerce-cloud/get-started/download-esw-cartridge) into your SFCC instance by appending the appropriate cartridge path to the site’s **cartridge path configuration**. The required cartridge path will vary depending on the site’s architecture. * **SFRA**: `int_eshopworld_sfra:int_eshopworld_eckout:int_eshopworld_core:app_storefront_base:modules` * **Site Genesis (SG)**: `int_eshopworld_controllers:int_eshopworld_eckout:int_eshopworld_core:SG_core:SG_controllers:modules` * **Progressive Web App (PWA)**: `int_eshopworld_pwa:int_eshopworld_eckout:int_eshopworld_core` * **Headless**: `int_eshopworld_headless:int_eshopworld_eckout:int_eshopworld_core` ### Steps to Configure Cartridge Path {% stepper %} {% step %} #### **Access Settings** Navigate to **Administration → Sites → Manage Sites → Your Site → Settings** {% endstep %} {% step %} #### **Append ESW Cartridge Path** In the **Cartridges** field, append the following path for **SFRA**:
{% endstep %} {% endstepper %} # Enable and Configure ESW Module How to enable and configure the ESW module in SFCC ### Enable and Configure ESW Module Navigate to **Merchant Tools → Site Preferences → Custom Preferences → ESW General Configuration** to enable the ESW module. ### Cartridge Setup Navigate to **Merchant Tools → Site Preferences → Custom Preferences → ESW General Configuration**
Within ESW General Configuration, specify: * **ESW Module Enabled:** This is a mandatory attribute. It enables or disables the ESW Module at the site level. * **ESW Allowed Languages:** The highlighted values represent languages to be considered as ESW Allowed Languages. * **ESW Base Currency:** It sets the default/base currency at the site level. * **Enable Geo Lookup (optional):** This option enables or disables the geo IP lookup. If the geo lookup is enabled, the shopper’s current location is determined when they access the site for the first time. If disabled, the country selectors are preselected with the first options from the selectors. The below values will be provided by the ESW integration team. * **ESW Retailer Brand Code (provided by IE):** This preference indicates the brand code of the current site. * **ESW Client ID for the Authorization Request:** Indicates the client ID. * **ESW Client Secret for Authorization Request:** Indicates the client secret. * **ESW Basic Auth Enabled:** This option enables or disables basic authentication. {% columns %} {% column %} {% hint style="info" %} #### Sandbox Instance The storefront uses **basic authentication**. If the storefront is protected, provide the **storefront username and password** for authentication. {% endhint %} {% endcolumn %} {% column %} {% hint style="info" %} #### Production Instance The retailer must provide **basic authentication credentials** to ESW. These credentials are used to configure **order confirmation endpoint basic authentication** on the ESW tenant side. {% endhint %} {% endcolumn %} {% endcolumns %}
* **ESW Production Client Secret:** For ESW pricing configuration enter the Client Secret for Price Feed authorization request. Navigate to **Merchant Tools > Site Preferences > Custom Preferences > ESW Pricing Configuration**.
# Run Initial Data Population Jobs How to run initial data population jobs in SFCC To finalize the setup, execute the key jobs that initialize essential data within SFCC. You can manually run a job from Business Manager to trigger specific backend processes as needed. ### Execute a job {% stepper %} {% step %} #### Access Jobs Navigate to Administration → Sites → Operations → Jobs {% endstep %} {% step %} #### Run the Job * Select the desired **job** from the list. * Click **Run**. * If the job is in **edit mode**, click **Run Now** instead. This step is **not required** for the fixed price model, where Pricing Advisor data is not in use.
{% endstep %} {% endstepper %} ### Key Jobs {% tabs %} {% tab title="Pricing Feed Job" %} #### Pricing Feed Job (`eswRetailerPricingFeed`) The `eswRetailerPricingFeed` job makes API calls to the retailer pricing feed and stores the retrieved data in a **custom object**. This data includes: * FX rates * Country adjustments * Duties and taxes per country {% hint style="info" %} #### Important behavior * The API call is **skipped** if the current day matches the day listed in the job’s preference. * The `ESW_PA_DATA` custom object is updated **only once per day**. * No further API calls are made for the remainder of that day. {% endhint %} {% endtab %} {% tab title="Auto-configurator" %} #### Retailer Auto-Configured Job (`eswRetailerAutoConfigurator`) The `eswRetailerAutoConfigurator` job creates **country** and **currency** custom objects based on Pricing Advisor data stored in the `ESW_PA_DATA` custom object. Prerequisite: The `eswRetailerPricingFeed` job must run successfully **before** executing this job to ensure that the necessary pricing data is available. {% hint style="info" %} #### Recommended schedule Run **bi-weekly** or **monthly**, or manually after a **country expansion**. {% endhint %} {% endtab %} {% tab title="Verify Results" %} #### Verifying the Results After running these jobs: 1. Navigate to **Merchant Tools → Custom Objects → Custom Object Editor** 2. Locate the `ESW_COUNTRIES` object. 3. Select the countries supported by ESW and define the applicable pricing models. ![Image](/files/08bd9824a74558b95b990334355b6d00c1be4dd2) {% endtab %} {% endtabs %} ### Scheduling a job Follow these steps to schedule a job. {% stepper %} {% step %} #### Open Job in Edit Mode Locate the desired job in **Business Manager** and open it in **edit mode**. {% endstep %} {% step %} #### Set Schedule * Click the **Schedule and History** tab. * Configure the scheduling details according to your requirements.
{% endstep %} {% endstepper %} ### Optional Manual Configuration Manual updates may be required for the following scenarios: * Base Currency * Pricing Model * Non-supported Countries {% tabs %} {% tab title="Base Currency" %} If the base currency differs from the site’s default, it should be configured accordingly. {% endtab %} {% tab title="Pricing Model" %} * By default, the pricing model is **dynamic/calculated**. * To switch to a **fixed** pricing model, check **'is Fixed Price Model'** in the country’s custom object. For more details, see ESW [Pricing Models](/salesforce-commerce-cloud/salesforce-commerce-cloud/pricing/pricing-models). {% endtab %} {% tab title="Non-supported Countries" %} Any country not supported by ESW must be added manually by the retailer. {% endtab %} {% endtabs %} # Shipping Methods Integration How to integrate shipping methods in SFCC The shipping methods displayed on the ESW checkout depend on the **ESW Override Shipping** custom preference in the **ESW Checkout Configuration**. {% tabs %} {% tab title="When ESW Override Shipping is enabled for a specific country" %} * ESW shipping methods are **overridden** with standard **SFCC shipping methods**. * The shipping method overrides are sent to ESW via the **Checkout API**. * The SFCC shipping methods are displayed during checkout. {% endtab %} {% tab title="When ESW Override Shipping is disabled for a specific country" %} * Shipping methods are retrieved from the **ESW tenant configuration**. * These ESW shipping methods are displayed during checkout. {% endtab %} {% endtabs %} ### Displaying the SFCC Shipping Methods Standard **SFCC shipping methods** are created with a specific currency. In the **custom site preference**, each shipping method ID is mapped to a specific country. {% stepper %} {% step %} #### Create Shipping Methods * Navigate to **Merchant Tools → Ordering → Shipping Methods** * Create shipping methods with: * **Shipping names** * **Types** for currencies available to shoppers in the storefront * Ensure each shipping method’s **name** and **type** are supported by **ESW**.
#### Example **Name** and **Type** of each shipping method must be supported by ESW. * `POST` for standard shipping * `EXP2` for express shipping The shipping method names must be either `POST` or `EXP2`. This naming rule is required by ESW. However, the ID can be any value. Configuring POST, EXP2, or any one of these two options for different currencies depends on the retailer’s business requirement. {% endstep %} {% step %} #### Configure Shipping Method IDs for the country Configure the IDs in a JSON format using the ESW Override Shipping custom site preference in [ESW Checkout Configuration](https://know.esw.com/space/TDR/1234637137/Merchant+Tools#ESW-Checkout-Configuration).
{% endstep %} {% step %} #### Display ESW shipping override methods * To display **ESW shipping override methods** on the cart page: * Enable custom preference **ESW Hide Native Shipping** in **ESW Retailer Display Configuration**
Once configured, the shipping methods are displayed at the checkout for the country.
{% endstep %} {% step %} #### Review the Go-Live Checklist Final step is to review the [Go-Live Checklist](https://know.esw.com/space/TDR/1234639052/Go-Live+Checklist) to ensure a successful launch. {% endstep %} {% step %} #### Verification on the Storefront After completing the configuration, verify the following: #### Currency and Pricing Ensure currency and pricing display correctly on: * **Product Display Page (PDP)** * **Product Listing Page (PLP)** * **Cart Page** #### ESW Storefront Components Confirm that ESW storefront components reflect the new configuration: * **Header** * **Footer** * **Country Selector** widget
Once pricing data is converted and supported countries are selected, the storefront is ready for validation.

{% endstep %} {% endstepper %} # Cartridge Installation Install the ESW SFCC cartridge. Choose steps for SFRA, Composable, OCAPI, or SiteGenesis Install the ESW cartridge into your SFCC codebase.
Architecture Install guide Cover image Cover image (dark)
Storefront Reference Architecture (SFRA) /spaces/GUPR15ARSjXiz9aZEsDU/pages/d4c777687961885f6bb72e48549cfd28fc78a515 /files/5GnetdEtwAyOgCnVPOF4 /files/4k8QzvXkxJrcF6f1N6Qb
Composable Storefront /spaces/GUPR15ARSjXiz9aZEsDU/pages/00e2846fd994f7365de4ea5a6478c59754401582 /files/Xmc6di5koSNJ6dIWC38S /files/N1KWxL1khowPdt7N8puF
Headless (OCAPI) /spaces/GUPR15ARSjXiz9aZEsDU/pages/2bbcf27440d894bdc982714891d277ec92358f80 /files/7LqmbUyabScyevpqJh7g /files/msrJH89A0knaIUpmiXFv
SiteGenesis /spaces/GUPR15ARSjXiz9aZEsDU/pages/fe54aab1045eb3404b2bf164996a084ca9d07185 /files/Jn0srx2zKmB977aG22C3 /files/5fTD1ThwbcqdPdfPqOS5
# SiteGenesis Install the ESW SFCC cartridge for a SiteGenesis storefront, including cartridge paths and site data import. Follow the steps below to install the ESW SiteGenesis cartridge for the first time: {% stepper %} {% step %} ### Clone the Repository Clone the cartridge source code to your local machine. {% endstep %} {% step %} ### Import the Cartridges * Import the following cartridges into your workspace: * `int_eshopworld_controllers` * `int_eshopworld_core` * Link both cartridges to your SFCC server connection. {% endstep %} {% step %} ### Import Site Data * Navigate to `Metadata > Sitesdata`. * Create a ZIP file for the site data folder (e.g., `sitesdata.zip`). * Import this ZIP file into your SFCC instance. {% endstep %} {% step %} ### Assign Cartridges to the Site Assign the `int_eshopworld_controllers` and `int_eshopworld_core` cartridges to the site’s cartridge path. The cartridge path sequence should look like this: ```rb int_eshopworld_controllers:int_eshopworld_core:app_storefront_base: ``` {% endstep %} {% step %} ### Assign Cartridges to Business Manager Assign the `int_eshopworld_controllers` and `int_eshopworld_core` cartridges to the business manager organization, for example: ```rb int_eshopworld_controllers:int_eshopworld_core:bm_custom_plugin ``` {% endstep %} {% endstepper %} # Composable Storefront Install the ESW PWA cartridge for SFCC Composable Storefront (PWA Kit), including site data, cartridge paths, and SCAPI setup.
SFCC PWA
The ESW PWA cartridge is developed for use with the SFCC PWA (SFCC Progressive Web-App) Kit. To use this cartridge make sure you already have a working PWA environment
Github
The Salesforce Commerce Cloud PWA Kit provides a modern, headless front-end framework for building Progressive Web App (PWA) storefronts on SFCC. https://github.com/SalesforceCommerceCloud/pwa-kit
## Installing the Cartridge (PWA) Follow these steps to install the ESW PWA cartridge for the first time: {% stepper %} {% step %} ### Clone the Repository Clone the ESW cartridge repository to your local development environment. {% endstep %} {% step %} ### Import the Cartridges Import the following cartridges into your workspace: * `int_eshopworld_pwa` * `int_eshopworld_core` {% endstep %} {% step %} ### Import Site Data * Navigate to `Metadata > Sitesdata` * Create a ZIP archive of the `sitesdata` folder (e.g., `sitesdata.zip`). * Import ZIP file into your SFCC instance via `Business Manager > Administration > Site Development > Import & Export` {% endstep %} {% step %} ### Assign Cartridges to the Site Assign the `int_eshopworld_pwa` and `int_eshopworld_core` cartridges to the site’s cartridge path. The cartridge path sequence should look like this: {% code title="cartridge path" %} ```rb int_eshopworld_pwa: int_eshopworld_core: app_someother_cartridge ``` {% endcode %} {% endstep %} {% step %} ### Configure SCAPI Add or update the SCAPI configuration as required to enable ESW endpoints for PWA storefront communication. {% endstep %} {% endstepper %} # Storefront Reference Architecture Install the ESW SFCC cartridge for an SFRA storefront, including site data import and site/Business Manager cartridge paths. Follow the steps below to install the ESW SFRA cartridge for the first time: {% stepper %} {% step %} **Clone the Repository** Clone the repository to your local machine. {% endstep %} {% step %} **Import the Cartridges** * Import the following cartridges into your workspace: * `int_eshopworld_sfra` * `int_eshopworld_core` * Link both cartridges to the server connection. {% endstep %} {% step %} **Import Site Data** * Navigate to `Metadata > Sitesdata` in the project. * Create a ZIP file of the `sitesdata` folder (e.g., `sitesdata.zip`). * Import this ZIP file into your SFCC instance. {% endstep %} {% step %} **Assign Cartridges to the Site** Assign the `int_eshopworld_sfra` and `int_eshopworld_core` cartridges to the site’s cartridge path. The cartridge path sequence should look like this: ```rb int_eshopworld_sfra:int_eshopworld_core:app_storefront_base: ``` {% endstep %} {% step %} **Assign Cartridges to Business Manager** Assign the `int_eshopworld_sfra` and `int_eshopworld_core` cartridges to the business manager organization, for example: ```rb int_eshopworld_sfra:int_eshopworld_core:bm_custom_plugin ``` {% endstep %} {% endstepper %} --- [Next Page](/llms-full.txt/1)

ESW Developer Documentation Portal

API References

Agentic Commerce Hub

Get Started with APIs

ESW Help Center and Client Hub

Client Hub

Help Center

Popular Topics

Visa

Mastercard

Test Scenario

Finance and Settlement

Making worldwide commerce simple

What this means

Visa

Mastercard

Test Scenario

Conditional

Conditional

Required for specific destinations

Conditional

Conditional

Conditional

Conditional

Conditional

If supplied

If supplied

International App

Payments App

ESW Pricing Advisor

Fixed prices in Shopify

:webhook:

Shopify Webhook

:webhook:

Shopify Webhook

:webhook:

:webhook:

:truck-fast:

ESW event

SFCC PWA

:github-alt: Github

Github