Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
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

Last updated

Was this helpful?