> For the complete documentation index, see [llms.txt](https://developer.esw.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.esw.com/order-api/resources/return-order-integration-event.md).
# Return Order Integration Event
Return Order Integration Event publishes the state of a return order, including:
* Return order header (status, return type/mode/method)
* Returned items, reasons, disposition, pricing and weight
* Shipping and carrier details (including manifests and drop-off locations)
* Return-level charges and credit breakdowns
Example Payload
{% code expandable="true" %}
```json
{
"ReturnOrderNumber": "RET-240315-000123",
"ReturnsListingsGuid": "4f0705a1-0c9f-4b01-9e8d-5a9e1c1a1234",
"CreatedOn": "2025-03-15T10:23:45Z",
"LastUpdated": "2025-03-15T11:05:12Z",
"UpdatedBy": "SYSTEM",
"Status": "Received",
"StatusReason": "Scanned at return centre",
"OriginCountryIso": "JP",
"DestinationCountryIso": "GB",
"ReturnType": "Refund",
"ReturnMode": "CourierDropOff",
"ReturnMethod": "PrepaidLabel",
"IsFirstReturnOrder": true,
"IsTotalReturn": false,
"ExpiresOn": "2025-04-14T23:59:59Z",
"ReturnItems": [
{
"Id": "a4fd50f8-84e7-4b2e-a0c9-31f7ccf2c111",
"ProductCode": "SKU-TSHIRT-BLACK-M",
"LineItemId": "1",
"Status": "Accepted",
"RejectionReason": null,
"ReturnReasons": [
{
"ReasonCode": "SIZE_TOO_SMALL",
"UnifiedReasonCode": "SIZE_FIT",
"ReasonComment": "Too tight across the chest",
"Description": "Size too small",
"IsRetailerAtFault": false,
"SuppliedBy": "SHOPPER"
}
],
"Disposition": {
"DispositionId": "GRADE-A",
"GradingType": "Resellable"
},
"ProductDetail": {
"Description": "Men's Essential T-Shirt",
"CustomsDescription": "Cotton t-shirt",
"ImageUrl": "https://example.com/images/tshirt-black-m.jpg",
"Color": "Black",
"Size": "M",
"Category": "Apparel",
"Personalized": false,
"DangerousGoods": false,
"ProhibitedForReturns": false,
"OverrideProhibitedForReturns": false,
"UnlimitedPeriodForReturns": false
},
"PricingAndWeight": {
"UnitPrice": {
"Amount": 29.99,
"Currency": "GBP"
},
"Weight": {
"WeightTotal": 0.35,
"WeightUnit": "kg"
}
},
"ReplacementInformation": {
"Type": "LikeForLike",
"Reason": "Replacement requested by shopper",
"IsReplacementFor": "ESW-240314-000987-1"
},
"ReturnOrderItemCharges": [
{
"Id": "f6eab54b-9d9e-4a91-8f8b-47e3ab5e9001",
"ReturnItemCharge": {
"ChargesInCurrency": [
{
"Type": "Refund",
"Charges": [
{
"Name": "ItemPrice",
"Value": {
"Amount": 29.99,
"Currency": "GBP"
}
},
{
"Name": "Tax",
"Value": {
"Amount": 5.0,
"Currency": "GBP"
}
}
]
},
{
"Type": "Fee",
"Charges": [
{
"Name": "RestockingFee",
"Value": {
"Amount": 2.0,
"Currency": "GBP"
}
}
]
}
]
}
}
]
}
],
"ShippingDetail": {
"Carrier": {
"CarrierServiceRouteId": "GB-RET-01",
"CarrierTrackingReference": "1Z999AA10123456784",
"BarcodeReference": "BR-RET-000123",
"EswLegacyCarrierIdentifier": "UPS_GB_RET",
"CarrierServiceCode": "STANDARD_RET",
"CarrierName": "UPS",
"ProviderName": 2
},
"ReturnCentre": {
"ReturnProcessedOn": "2025-03-15T11:02:30Z",
"ReturnAdminCentreCode": "GB-RET-CENTRE-01"
},
"ManifestDetail": {
"ManifestId": "MAN-RET-240315-001",
"ManifestTrackingStatus": "Closed",
"AirCarrierDetails": {
"FlightNumber": "BA008",
"AirWaybill": "AWB-1234567890",
"Departure": {
"Airport": "NRT",
"Time": "2025-03-14T22:15:00Z"
},
"Arrival": {
"Airport": "LHR",
"Time": "2025-03-15T05:10:00Z"
}
},
"PackageAndWeight": {
"Pallets": 0,
"Cartons": 1,
"TotalWeightKg": 0.35
},
"ClosedOn": "2025-03-15T11:10:00Z",
"CreatedOn": "2025-03-15T10:50:00Z"
},
"ContainerId": "CONT-000045",
"DropOffLocation": {
"Id": "LOC-12345",
"Type": "PUDO",
"Name": "Main Street Drop-Off",
"Address": {
"Address1": "123 Main Street",
"Address2": "Suite 4B",
"Address3": "District 1",
"City": "Tokyo",
"Postcode": "100-0001",
"Sortcode": "123456",
"Region": "Tokyo",
"Country": "JP"
}
}
},
"PaidBy": "Shopper",
"ReturnOrderCharges": [
{
"ChargesInCurrency": [
{
"Type": "ReturnShippingFee",
"Charges": [
{
"Name": "ReturnShipping",
"Value": {
"Amount": 4.99,
"Currency": "GBP"
}
}
]
},
{
"Type": "Adjustment",
"Charges": [
{
"Name": "GoodwillCredit",
"Value": {
"Amount": -3.0,
"Currency": "GBP"
}
}
]
}
]
}
],
"OutboundOrderDetail": {
"OrderReference": "ESW-240314-000987",
"OrderSource": "WEB",
"ShipmentReference": "SHIP-240314-000987"
},
"CreditBreakdowns": [
{
"OrderArticleId": "5974b83e-c121-43f8-8d71-93edcf545a1d",
"CreditTypeId": 1,
"MonolithOrderArticleId": 123456,
"CreditRuleId": "aaf3f4de-6a3e-4c3c-b8ae-5d0f6a8b1234",
"MonolithCreditRuleId": 7890,
"CreditsInCurrency": [
{
"Type": "Refund",
"Charges": [
{
"Name": "ItemRefund",
"Value": {
"Amount": 34.99,
"Currency": "GBP"
}
}
]
},
{
"Type": "FeeWaiver",
"Charges": [
{
"Name": "RestockingFeeWaived",
"Value": {
"Amount": 2.0,
"Currency": "GBP"
}
}
]
}
]
}
],
"TenantCode": "GOCAS",
"OrganisationId": "2f1e3b9d-8c20-4b07-9d71-4e02e2b91234"
}
```
{% endcode %}
Return Order Integration Event Attributes
| Field Name | Description | Field Type | Example of Data |
| --------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------- |
| `ReturnOrderNumber` | Unique reference for the return order assigned by ESW. | String | `"RET-240315-000123"` |
| `ReturnsListingsGuid` | ESW GUID for the return listing. | String (GUID) | `"4f0705a1-0c9f-4b01-9e8d-5a9e1c1a1234"` |
| `CreatedOn` | Date and time when the return order was created. | String (ISO 8601, date-time) | `"2025-03-15T10:23:45Z"` |
| `LastUpdated` | Date and time when the return order was last updated. | String (ISO 8601, date-time) | `"2025-03-15T11:05:12Z"` |
| `UpdatedBy` | Source of the latest update. | String | `"SYSTEM"` |
| `Status` | Current status of the return order. | String | `"Received"` |
| `StatusReason` | Extra context for the current status. | String | `"Scanned at return centre"` |
| `OriginCountryIso` | ISO code for the shopper's return country. | String (ISO 3166-1 alpha-2) | `"JP"` |
| `DestinationCountryIso` | ISO code for the return destination country. | String (ISO 3166-1 alpha-2) | `"GB"` |
| `ReturnType` | Return outcome, such as refund or replacement. | String | `"Refund"` |
| `ReturnMode` | How the shopper sends the return. | String | `"CourierDropOff"` |
| `ReturnMethod` | Return service offered to the shopper. | String | `"PrepaidLabel"` |
| `IsFirstReturnOrder` | Whether this is the first return for the outbound order. | Boolean | `true` |
| `IsTotalReturn` | Whether the return includes all items from the original order. | Boolean | `false` |
| `ExpiresOn` | When the return label or authorisation expires. | String (ISO 8601, date-time) | `"2025-04-14T23:59:59Z"` |
| `PaidBy` | Party responsible for return charges. | String | `"Shopper"` |
| `TenantCode` | ESW tenant identifier for the brand/retailer. | String | `"GOCAS"` |
| `OrganisationId` | ESW organisation identifier. | String (GUID) | `"2f1e3b9d-8c20-4b07-9d71-4e02e2b91234"` |
| `ReturnItems` | Return line items in the return order. | Array of objects | `[ { ... } ]` |
| `ReturnItems[].Id` | Unique identifier for the return item. | String (GUID) | `"a4fd50f8-84e7-4b2e-a0c9-31f7ccf2c111"` |
| `ReturnItems[].ProductCode` | Brand’s product code / SKU for the returned item. | String | `"SKU-TSHIRT-BLACK-M"` |
| `ReturnItems[].LineItemId` | Original order line item identifier. | String | `"1"` |
| `ReturnItems[].Status` | Status of the return item. | String | `"Accepted"` |
| `ReturnItems[].RejectionReason` | Rejection reason, if the item was rejected. | String or `null` | `null` |
| `ReturnItems[].ReturnReasons` | Reasons recorded for the return item. | Array of objects | `[ { ... } ]` |
| `ReturnItems[].ReturnReasons[].ReasonCode` | Shopper return reason code. | String | `"SIZE_TOO_SMALL"` |
| `ReturnItems[].ReturnReasons[].UnifiedReasonCode` | Normalised ESW return reason code. | String | `"SIZE_FIT"` |
| `ReturnItems[].ReturnReasons[].ReasonComment` | Free-text comment for the return reason. | String | `"Too tight across the chest"` |
| `ReturnItems[].ReturnReasons[].Description` | Human-readable return reason. | String | `"Size too small"` |
| `ReturnItems[].ReturnReasons[].IsRetailerAtFault` | Whether the retailer was at fault. | Boolean | `false` |
| `ReturnItems[].ReturnReasons[].SuppliedBy` | Source of the return reason. | String | `"SHOPPER"` |
| `ReturnItems[].Disposition` | Return centre grading details for the item. | Object | `{ "DispositionId": "GRADE-A", ... }` |
| `ReturnItems[].Disposition.DispositionId` | Disposition outcome identifier. | String | `"GRADE-A"` |
| `ReturnItems[].Disposition.GradingType` | Grading classification for the item. | String | `"Resellable"` |
| `ReturnItems[].ProductDetail` | Product details used for display and customs. | Object | `{ "Description": "Men's Essential T-Shirt", ... }` |
| `ReturnItems[].ProductDetail.Personalized` | Whether the product is personalised. | Boolean | `false` |
| `ReturnItems[].ProductDetail.DangerousGoods` | Whether the item is classed as dangerous goods. | Boolean | `false` |
| `ReturnItems[].ProductDetail.ProhibitedForReturns` | Whether the item is normally non-returnable. | Boolean | `false` |
| `ReturnItems[].ProductDetail.OverrideProhibitedForReturns` | Whether the non-returnable rule was overridden. | Boolean | `false` |
| `ReturnItems[].ProductDetail.UnlimitedPeriodForReturns` | Whether the item has no return window limit. | Boolean | `false` |
| `ReturnItems[].PricingAndWeight` | Price and weight details for the return item. | Object | `{ "UnitPrice": { ... }, "Weight": { ... } }` |
| `ReturnItems[].PricingAndWeight.UnitPrice.Amount` | Monetary amount for a single unit of the product. | Number | `29.99` |
| `ReturnItems[].PricingAndWeight.UnitPrice.Currency` | Currency of the unit price. | String (ISO 4217) | `"GBP"` |
| `ReturnItems[].PricingAndWeight.Weight.WeightTotal` | Total weight of the item, including packaging if used. | Number | `0.35` |
| `ReturnItems[].PricingAndWeight.Weight.WeightUnit` | Unit of measurement for weight. | String | `"kg"` |
| `ReturnItems[].ReplacementInformation` | Replacement details for return items in replacement flows. | Object | `{ "Type": "LikeForLike", ... }` |
| `ReturnItems[].ReplacementInformation.Type` | Replacement type. | String | `"LikeForLike"` |
| `ReturnItems[].ReplacementInformation.Reason` | Reason for the replacement. | String | `"Replacement requested by shopper"` |
| `ReturnItems[].ReplacementInformation.IsReplacementFor` | Reference to the item or line being replaced. | String | `"ESW-240314-000987-1"` |
| `ReturnItems[].ReturnOrderItemCharges` | Item-level charge and refund breakdown. | Array of objects | `[ { "ReturnItemCharge": { ... } } ]` |
| `ReturnItems[].ReturnOrderItemCharges[].Id` | Unique identifier for the item charge record. | String (GUID) | `"f6eab54b-9d9e-4a91-8f8b-47e3ab5e9001"` |
| `ReturnItems[].ReturnOrderItemCharges[].ReturnItemCharge.ChargesInCurrency[].Type` | Charge type, such as `Refund` or `Fee`. | String | `"Refund"` |
| `ReturnItems[].ReturnOrderItemCharges[].ReturnItemCharge.ChargesInCurrency[].Charges[].Name` | Charge component name. | String | `"ItemPrice"` |
| `ReturnItems[].ReturnOrderItemCharges[].ReturnItemCharge.ChargesInCurrency[].Charges[].Value` | Charge amount and currency. | Object (`UnitPrice`) | `{ "Amount": 29.99, "Currency": "GBP" }` |
| `ShippingDetail` | Shipping details for the return shipment. | Object | `{ "Carrier": { ... }, "ReturnCentre": { ... } }` |
| `ShippingDetail.Carrier` | Carrier and service details. | Object | `{ "CarrierName": "UPS", ... }` |
| `ShippingDetail.Carrier.CarrierName` | Display name of the carrier used for the return. | String | `"UPS"` |
| `ShippingDetail.Carrier.CarrierTrackingReference` | Carrier tracking reference. | String | `"1Z999AA10123456784"` |
| `ShippingDetail.Carrier.ProviderName` | Numeric carrier provider value. | Integer | `2` (e.g. `Centiro`) |
| `ShippingDetail.ReturnCentre` | ESW return centre details. | Object | `{ "ReturnProcessedOn": "...", "ReturnAdminCentreCode": "..." }` |
| `ShippingDetail.ManifestDetail.ManifestId` | Manifest identifier for the return shipment. | String | `"MAN-RET-240315-001"` |
| `ShippingDetail.ManifestDetail.ManifestTrackingStatus` | Manifest status. | String | `"Closed"` |
| `ShippingDetail.ManifestDetail.PackageAndWeight` | Package count and weight summary for the manifest. | Object | `{ "Cartons": 1, "TotalWeightKg": 0.35 }` |
| `ShippingDetail.DropOffLocation` | Shopper drop-off location details, if used. | Object | `{ "Name": "Main Street Drop-Off", "Address": { ... } }` |
| `ReturnOrderCharges` | Return-level charge breakdown. | Array of objects | `[ { "ChargesInCurrency": [ ... ] } ]` |
| `ReturnOrderCharges[].ChargesInCurrency[].Type` | Return-order charge type. | String | `"ReturnShippingFee"` |
| `ReturnOrderCharges[].ChargesInCurrency[].Charges[].Name` | Return-order charge component name. | String | `"ReturnShipping"` |
| `ReturnOrderCharges[].ChargesInCurrency[].Charges[].Value` | Return-order charge amount and currency. | Object (`UnitPrice`) | `{ "Amount": 4.99, "Currency": "GBP" }` |
| `OutboundOrderDetail` | Original outbound order and shipment references. | Object | `{ "OrderReference": "ESW-240314-000987", ... }` |
| `OutboundOrderDetail.OrderReference` | Original outbound order reference. | String | `"ESW-240314-000987"` |
| `OutboundOrderDetail.OrderSource` | Source channel of the outbound order. | String | `"WEB"` |
| `OutboundOrderDetail.ShipmentReference` | Original outbound shipment reference, if available. | String | `"SHIP-240314-000987"` |
| `CreditBreakdowns` | Item-level credit and refund breakdown. | Array of objects | `[ { "CreditTypeId": 1, "CreditsInCurrency": [ ... ] } ]` |
| `CreditBreakdowns[].OrderArticleId` | Original order article identifier for the credit entry. | String (GUID) | `"5974b83e-c121-43f8-8d71-93edcf545a1d"` |
| `CreditBreakdowns[].CreditTypeId` | Numeric credit type identifier. | Integer | `1` |
| `CreditBreakdowns[].MonolithOrderArticleId` | Legacy article identifier for the same credit entry. | Integer | `123456` |
| `CreditBreakdowns[].CreditRuleId` | Applied credit rule identifier. | String (GUID) | `"aaf3f4de-6a3e-4c3c-b8ae-5d0f6a8b1234"` |
| `CreditBreakdowns[].MonolithCreditRuleId` | Legacy identifier for the credit rule. | Integer | `7890` |
| `CreditBreakdowns[].CreditsInCurrency[].Type` | Credit type in the monetary breakdown. | String | `"Refund"` |
| `CreditBreakdowns[].CreditsInCurrency[].Charges[].Name` | Credit component name. | String | `"ItemRefund"` |
| `CreditBreakdowns[].CreditsInCurrency[].Charges[].Value` | Credit amount and currency. | Object (`UnitPrice`) | `{ "Amount": 34.99, "Currency": "GBP" }` |
#### Other Definitions
**ReturnType**\
Describes the *business outcome* of the return from the shopper’s perspective, such as:
* `Refund` – shopper will be refunded
* `Replacement` – shopper will receive a replacement item
* `StoreCredit` – shopper will receive credit or voucher
**ReturnMode**\
Defines *how* the shopper returns the goods, e.g.:
* `CourierPickup` – a courier collects from the shopper’s address
* `CourierDropOff` – shopper drops off at a PUDO/parcel shop
* `Postal` – shopper uses a postal network
**ReturnMethod**\
Represents the *return product* or channel, for example:
* `PrepaidLabel` – shopper prints a prepaid label
* `Paperless` – shopper uses a QR/paperless return
* `CustomerPaid` – shopper pays for shipping directly
**IsFirstReturnOrder vs IsTotalReturn**
* `IsFirstReturnOrder` – `true` if this is the first return raised against the original order.
* `IsTotalReturn` – `true` if **all** articles from the original order are being returned in this event.
These flags help determine:
* Whether additional partial returns are expected in future.
* Whether full-order business rules apply (e.g. full duty/tax refunds, free return promotions).
**CreditBreakdowns**
The `CreditBreakdowns` collection provides **fine-grained visibility** on how refunds or credits were calculated for each article, aligned to ESW credit rules. Each entry links:
* `OrderArticleId` – the original order article
* `CreditTypeId` / `CreditRuleId` – the type and rule used
* `CreditsInCurrency` – the monetary values by charge type and currency
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.esw.com/order-api/resources/return-order-integration-event.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.