> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/returns-api/resources/tutorials/creating-a-return-order.md). # Creating a Return Order Creating a return order registers the shopper's intent to return one or more items, assigns a carrier and method, and returns a `returnOrderNumber` that identifies the return throughout its lifecycle. ```http POST /{identifier}/orders/{orderReference}/return-orders Authorization: Bearer Content-Type: application/json ``` *** {% stepper %} {% step %} ### When to call this endpoint Call this endpoint when: * A shopper has selected the items they want to return and chosen a return method * A customer service agent is creating a return on the shopper's behalf * An automated process is creating a return (e.g. for an undeliverable parcel) **Prerequisites:** 1. The outbound order must exist in the platform (`POST /outbound-orders`) 2. Available return methods must have been retrieved (`POST /return-methods/{orderReference}`) 3. For PUDO returns, a specific drop-off location must have been selected {% endstep %} {% step %} ### Request structure {% code expandable="true" %} ```json POST /MYBRAND/orders/ORD-2024-78542/return-orders { "consumerEmailAddress": "jane.smith@example.com", "cultureLanguageIso": "en-US", "returnItems": [ ... ], "returnMethod": "Postal", "returnType": "Normal", "isPaperlessRoute": false, "paidBy": "Retailer", "carrierIdentifier": "Ascendia", "shippingReference": "REF6993876423", "barcodeReference": "5 012345 678900", "carrierReference": "FBA_1636646500B", "weight": { "weightTotal": 1.2, "weightUnit": "KG" }, "returnAdminCentreCodeOverride": "IEDUB" } ``` {% endcode %} Fields in the request body are optional in the schema, but most are effectively required for the return to be processed correctly. The sections below explain each field. {% endstep %} {% step %} ### `consumerEmailAddress` and `cultureLanguageIso` #### `consumerEmailAddress` The shopper's email address. ESW uses this to send return confirmation emails and tracking updates. ```json "consumerEmailAddress": "jane.smith@example.com" ``` Always provide this — without it the shopper will not receive automated return communications. #### `cultureLanguageIso` The shopper's language and locale preference in BCP 47 format. Used to localise return communications and portal content. ```json "cultureLanguageIso": "en-US" ``` Use the same format as the outbound order: ISO 639-1 language code + ISO 3166-1 country code, hyphen-separated (`"fr-FR"`, `"de-DE"`, `"ja-JP"`). {% endstep %} {% step %} ### `returnItems` — items and reason codes `returnItems` is an array of `ReturnItemRequestDto` objects identifying which items the shopper is returning and why. ```json "returnItems": [ { "id": "653995b0-d9e6-4018-9b85-d66d051b57e7", "productCode": "SKU-00123", "lineItemId": "1", "reasonCode": "WrongItemShipped", "reasonComment": "Received blue, ordered black" }, { "id": "7a4c12e1-f3b2-4891-c73d-e88f162a9b45", "productCode": "SKU-00456", "lineItemId": "2", "reasonCode": "DoesNotFit", "reasonComment": "Too small — need a larger size" } ] ``` #### `ReturnItemRequestDto` fields | Field | Type | Description | | --------------- | ------------- | ------------------------------------------------------------------------------------- | | `id` | string (UUID) | The return item identifier — use the same UUID from the return methods search request | | `productCode` | string | The SKU being returned — must match the product code on the original order | | `lineItemId` | string | The line item ID on the original order | | `reasonCode` | string | The shopper's reason for returning — see below | | `reasonComment` | string | Free-text additional detail from the shopper | #### `reasonCode` values `reasonCode` is a free-text string, not a constrained enum. The specific values available to your brand are configured by ESW and retrieved via the country configuration endpoint. Common values include: | Code | Meaning | | -------------------- | ------------------------------------------ | | `"WrongItemShipped"` | Retailer sent the wrong product | | `"DoesNotFit"` | Incorrect size | | `"Defective"` | Item arrived damaged or faulty | | `"NotAsDescribed"` | Item does not match the online description | | `"ChangedMind"` | Shopper no longer wants the item | | `"QualityIssue"` | Quality not as expected | | `"DamagedInTransit"` | Item damaged during delivery | Use the reason codes from `GET /configuration/countries/{countryIso}` for the definitive list applicable to your brand and market. #### The `id` field — continuity across the flow Use the same UUID for each item's `id` across the return methods search and return order creation requests. This links the item through the return flow and ensures ESW can trace each item's journey consistently. {% endstep %} {% step %} ### `returnMethod`, `returnType`, and `paidBy` #### `returnMethod` Must match the `returnMethod` the shopper selected from the return methods search response. Do not use a method that was not offered in that response. ```json "returnMethod": "Postal" ``` | Value | Description | | --------------- | -------------------------------------------------- | | `"Postal"` | Post office drop-off with a prepaid label | | `"PUDO"` | Drop-off at a designated pick-up/drop-off location | | `"Collections"` | Carrier collection from the shopper's address | #### `returnType` Describes the nature of the return. For shopper-initiated returns from a portal, this is almost always `"Normal"`. See Step 11 for all four values and when to use each. ```json "returnType": "Normal" ``` #### `paidBy` Must match the `paidBy` from the selected return method in the search response. ```json "paidBy": "Retailer" ``` | Value | Meaning | | ------------- | ------------------------------------------------- | | `"Retailer"` | Retailer covers the return shipping cost | | `"Shopper"` | Shopper pays for return shipping | | `"Unpaid"` | No prepaid label — shopper arranges independently | | {% endstep %} | | {% step %} ### `isPaperlessRoute` Indicates whether this return uses a paperless label flow. Must match the `isPaperlessRoute` value from the selected carrier service route in the search response. ```json "isPaperlessRoute": false ``` When `true`, the shopper presents a QR code at the carrier location instead of a printed label. ESW uses this flag to determine which label generation process to use. {% endstep %} {% step %} ### Carrier and reference fields #### `carrierIdentifier` The ESW carrier identifier — use the `eswCarrierIdentifier` value from the `carrierServiceRoute` in the return methods search response. Do not use the consumer-facing `carrierName`. ```json "carrierIdentifier": "Ascendia" ``` #### `shippingReference` Your internal shipping reference for this return. This appears on the return label and is used for tracking. ```json "shippingReference": "REF6993876423" ``` #### `barcodeReference` The barcode that will be used on the return label — typically a pre-generated barcode value assigned by your system or the carrier. ```json "barcodeReference": "5 012345 678900" ``` #### `carrierReference` The carrier's own tracking reference for this return shipment. ```json "carrierReference": "FBA_1636646500B" ``` Not all carrier routes require all three reference fields. Provide what you have available — ESW will generate references for any fields not supplied if your route configuration supports this. {% endstep %} {% step %} ### `dropOffLocation` — PUDO returns `dropOffLocation` is required when `returnMethod` is `"PUDO"` and `isLocationRequired` was `true` in the search response. It identifies the specific PUDO location the shopper will use. ```json "dropOffLocation": { "id": "P73", "type": "Pudo", "name": "UPS Store — 5th Avenue", "address1": "1385 Fifth Avenue", "city": "New York", "postcode": "10029", "region": "NY", "country": "US", "telephone": "+12125551234", "openingTimesDescription": "Mon–Fri 09:00–18:00, Sat 10:00–16:00" } ```
DropOffLocationDto fields | Field | Required | Description | | ------------------------- | -------- | ---------------------------------------------------------- | | `id` | ✅ | The location identifier from the `GET /location/` response | | `type` | ❌ | `"Store"` or `"Pudo"` | | `name` | ❌ | Display name of the location | | `address1` | ❌ | Primary address line | | `address2` | ❌ | Secondary address line | | `address3` | ❌ | Tertiary address line | | `city` | ❌ | City | | `postcode` | ❌ | Postcode | | `sortcode` | ❌ | Sort code (carrier routing) | | `region` | ❌ | Region or state | | `country` | ❌ | Country name | | `telephone` | ❌ | Location phone number | | `email` | ❌ | Location email | | `openingTimesDescription` | ❌ | Free-text opening hours | | `openingTimes` | ❌ | Structured opening times array |
The `id` is the critical field — it links to the location record in ESW's system. The address fields are stored for display purposes in ESW's returns portal and shopper communications. {% endstep %} {% step %} ### `weight` The estimated or actual weight of the return parcel. ```json "weight": { "weightTotal": 1.2, "weightUnit": "KG" } ``` | Field | Type | Description | | ------------- | --------------- | ----------------------------------------------------- | | `weightTotal` | number (double) | Total weight of the return parcel including packaging | | `weightUnit` | enum | `"KG"` or `"LB"` | Weight is used for customs declarations on the return shipment. If the shopper does not know the exact weight, use an estimate based on the items being returned. {% endstep %} {% step %} ### `returnAdminCentreCodeOverride` ESW automatically selects the appropriate returns warehouse (admin centre) based on the order's routing configuration. In most cases, you do not need to set this. ```json "returnAdminCentreCodeOverride": "IEDUB" ``` Use this field only when: * You want to direct the return to a specific admin centre that differs from the automatically selected one * You retrieved `selectedReturnAdminCentreCode` from the return methods search and want to pin the return to that centre * ESW support has instructed you to use a specific override for a routing issue The value must be a valid admin centre code as configured in ESW's system (e.g. `"IEDUB"`, `"AUCOW"`, `"RUMDC"`). {% endstep %} {% step %} ### All four `ReturnType` values #### `"Normal"` — standard shopper-initiated return ```json "returnType": "Normal" ``` The most common type. The shopper initiates the return through the portal or a CS agent initiates it on their behalf. The item was delivered and the shopper wants to return it. **Use for:** All standard shopper-initiated returns from the returns portal. #### `"Undeliverable"` — parcel could not be delivered ```json "returnType": "Undeliverable" ``` The original outbound parcel could not be delivered to the shopper — address not found, shopper not available for repeated delivery attempts, customs refused entry — and is being returned to the retailer. **Use for:** Automated return creation by ESW or logistics systems when a delivery fails and the parcel is returning. **Note:** This type is typically created by ESW's systems rather than by retailer API calls. If you are creating undeliverable returns programmatically, confirm the flow with your ESW integration contact. #### `"BlindReturn"` — unsolicited return received ```json "returnType": "BlindReturn" ``` A parcel arrived at ESW's returns warehouse without a prior return order being created — the shopper returned goods directly without going through the returns portal. **Use for:** Creating a return order retrospectively to process goods already physically received at the warehouse. **Operational note:** ESW's returns warehouse team typically creates these, not retailer systems. #### `"EUCoolingOff"` — EU statutory cooling-off period return ```json "returnType": "EUCoolingOff" ``` A return initiated under the EU Consumer Rights Directive 14-day cooling-off period. The shopper has a statutory right to return without providing a reason within 14 days of receipt. **Use for:** Returns from EU shoppers who explicitly invoke their cooling-off rights. Some brands configure different return policies or refund speeds for this type. **Legal note:** Always confirm with your legal team which orders and markets are subject to the EU cooling-off period requirements. {% endstep %} {% step %} ### The creation response A successful `POST /return-orders` returns `200 OK` with `CreateReturnOrderWebResponse`. {% code expandable="true" %} ```json { "returnsListingsGuid": "4c071f76-e27b-4291-a29h1-e2d349a12345", "returnOrderNumber": "5000002303", "returnType": "Normal", "returnMethod": "Postal", "paidBy": "Retailer", "carrierIdentifier": "Ascendia", "isPaperlessRoute": false, "returnItems": [ { "id": "653995b0-d9e6-4018-9b85-d66d051b57e7", "productCode": "SKU-00123", "lineItemId": "1", "productDescription": "Classic Leather Wallet", "productImageUrl": "https://cdn.brand.com/images/sku-00123.jpg", "color": "Tan", "size": "One Size", "category": "ApparelAccessories", "reasonCode": "WrongItemShipped", "reasonComment": "Received blue, ordered black" } ], "weight": { "weightTotal": 1.2, "weightUnit": "KG" } } ``` {% endcode %} #### Key response fields to store | Field | Description | How to use | | --------------------- | ------------------------------------------------------------ | --------------------------------------------------------------------- | | `returnOrderNumber` | The primary identifier for this return — e.g. `"5000002303"` | Store this. Used in all subsequent operations: `GET`, `PUT`, tracking | | `returnsListingsGuid` | UUID linking this return to ESW's listings system | Store for audit and reporting | | `returnItems[n].id` | The UUID for each returned item | Use in `PUT /return-orders` when updating item status | | `isPaperlessRoute` | Confirmed paperless status | Use to determine label vs QR code generation in your UI | | {% endstep %} | | | {% step %} ### Examples {% hint style="info" icon="arrow-progress" %} #### Example A — Postal return, retailer-paid, with label {% endhint %} Standard single-item postal return. Shopper wants to return a wallet that was the wrong colour. {% code expandable="true" %} ```json POST /MYBRAND/orders/ORD-2024-78542/return-orders { "consumerEmailAddress": "jane.smith@example.com", "cultureLanguageIso": "en-US", "returnItems": [ { "id": "653995b0-d9e6-4018-9b85-d66d051b57e7", "productCode": "SKU-00123", "lineItemId": "1", "reasonCode": "WrongItemShipped", "reasonComment": "Received blue, ordered black" } ], "returnMethod": "Postal", "returnType": "Normal", "isPaperlessRoute": false, "paidBy": "Retailer", "carrierIdentifier": "Ascendia", "shippingReference": "REF6993876423", "barcodeReference": "5 012345 678900", "weight": { "weightTotal": 0.3, "weightUnit": "KG" }, "returnAdminCentreCodeOverride": "IEDUB" } ``` {% endcode %} {% hint style="info" icon="arrow-progress" %} #### Example B — PUDO return, paperless QR code {% endhint %} Shopper selected a UPS PUDO location for a paperless return. {% code expandable="true" %} ```json POST /MYBRAND/orders/ORD-2024-78543/return-orders { "consumerEmailAddress": "sophie.nguyen@example.com", "cultureLanguageIso": "en-AU", "returnItems": [ { "id": "7a4c12e1-f3b2-4891-c73d-e88f162a9b45", "productCode": "SKU-00789", "lineItemId": "3", "reasonCode": "DoesNotFit", "reasonComment": "Size M too small — usually wear L" } ], "returnMethod": "PUDO", "returnType": "Normal", "isPaperlessRoute": true, "paidBy": "Retailer", "carrierIdentifier": "UPS_PUDO", "weight": { "weightTotal": 0.5, "weightUnit": "KG" }, "dropOffLocation": { "id": "P73", "type": "Pudo", "name": "UPS Store — Sydney CBD", "address1": "45 Clarence Street", "city": "Sydney", "postcode": "2000", "region": "NSW", "country": "Australia", "telephone": "+61293741000", "openingTimesDescription": "Mon–Fri 08:30–18:00" } } ``` {% endcode %} {% hint style="info" icon="arrow-progress" %} #### Example C — Multi-item return, two different reasons {% endhint %} {% code expandable="true" %} ```json POST /MYBRAND/orders/ORD-2024-78544/return-orders { "consumerEmailAddress": "marc.dupont@example.com", "cultureLanguageIso": "fr-FR", "returnItems": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "productCode": "SKU-00456", "lineItemId": "2", "reasonCode": "Defective", "reasonComment": "Boucle cassée à la réception" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "productCode": "SKU-00789", "lineItemId": "3", "reasonCode": "ChangedMind", "reasonComment": "N'aime pas la couleur" } ], "returnMethod": "Postal", "returnType": "Normal", "isPaperlessRoute": false, "paidBy": "Retailer", "carrierIdentifier": "LaPoste", "weight": { "weightTotal": 0.85, "weightUnit": "KG" } } ``` {% endcode %} {% hint style="info" icon="arrow-progress" %} #### Example D — EU cooling-off return {% endhint %} Shopper in Germany invoking their statutory 14-day right to return, no reason required. {% code expandable="true" %} ```json POST /MYBRAND/orders/ORD-2024-78545/return-orders { "consumerEmailAddress": "hans.muller@example.de", "cultureLanguageIso": "de-DE", "returnItems": [ { "id": "c3d4e5f6-a7b8-9012-cdef-234567890123", "productCode": "SKU-00123", "lineItemId": "1", "reasonCode": "ChangedMind" } ], "returnMethod": "Postal", "returnType": "EUCoolingOff", "isPaperlessRoute": false, "paidBy": "Retailer", "carrierIdentifier": "DHL", "weight": { "weightTotal": 0.2, "weightUnit": "KG" } } ``` {% endcode %} {% endstep %} {% step %} ### Common errors | Status | Cause | Fix | | ------------------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------------------- | | `404` on `{orderReference}` | Outbound order not found | Call `POST /outbound-orders` before creating the return order | | `400` — invalid `returnMethod` | Unknown enum value | Use `Postal`, `PUDO`, or `Collections` | | `400` — invalid `returnType` | Unknown enum value | Use `Normal`, `Undeliverable`, `BlindReturn`, or `EUCoolingOff` | | `400` — `dropOffLocation` missing | `returnMethod` is `PUDO` but no location provided | Include `dropOffLocation` with at least `id` for PUDO returns | | `400` — `carrierIdentifier` not configured | Unknown carrier | Use the `eswCarrierIdentifier` from the return methods search — not `carrierName` | | `400` — `weightUnit` invalid | Unknown enum value | Use `KG` or `LB` | | {% endstep %} | | | | {% endstepper %} | | | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.esw.com/returns-api/resources/tutorials/creating-a-return-order.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.