> 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/returns-api-v3.0/methods/return-methods.md). # Return Methods The following are the methods associated with the ‘Return’ API data type: ## GET Return (Using ID) This method can be used to retrieve a return order using the *Return Order Number* fed back during the *Create Return* call. To get the return information send a GET request to {% code expandable="true" %} ```http GET /orders/{orderReference}/return-orders/{returnOrderNumber} ``` {% endcode %} ### Method Parameters
Request Parameters | **Field Name** | **Data Type** | **Required/Optional** | **Description** | | ----------------- | --------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------- | | orderReference |

string

(max 30 char)

| Required |

The retailer’s unique reference associated with the order.

This is case-insensitive.

| | returnOrderNumber | ulong | Required | The return order number in the return platform. |
Response Parameters | **Field Name** | **Type** | **Description** | | ------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | string | The Return Order identifier. | | orderReference | string | The Retailer’s unique reference for the order. | | returnOrderNumber | ulong | Return order number. | | createdOn | dateTime | Date-Time in UTC format of when the return was created. | | lastUpdated | dateTime | Date-Time in UTC format of when the return was last updated. | | status | string | Overall status of the return. | | returnAdminCentreCode | string | Returns centre used for the return. | | returnsListingsGuid | guid | Unique GUID for the return order. | | returnType | enum |

Type of return

Example: BlindReturn, Undeliverable, Normal etc.

| | returnMethod | enum |

Method used for shipping the return.

Example: Postal, PUDO, Collections

| | isPaperlessRoute | boolean | Flag to check if the return order sends out QR code for paperless Pick-up/Drop-off. | | paidBy | enum |

The party that paid for the return.

Example: Unpaid, Retailer, Shopper

| | carrierIdentifier | string | Unique identifier of the shipping carrier. | | dropOffLocation | object | | | dropOffLocation.id | string | The ID of the location. | | dropOffLocation.type | enum |

Location type

Example: Store, PUDO

| | dropOffLocation.name | string | The name of the drop-off location. | | dropOffLocation.address1 | string | The first line of the address of the drop-off location. | | dropOffLocation.address2 | string | The second line of the address of the drop-off location. | | dropOffLocation.address3 | string | The third line of the address of the drop-off location. | | ropOffLocation.city | string | The city of the drop-off location. | | dropOffLocation.postcode | string | The postcode of the drop-off location. | | dropOffLocation.sortcode | string | The sort code of the drop-off location. | | dropOffLocation.region | string | The region of the drop-off location. | | dropOffLocation.country | string | The country of the drop-off location. | | dropOffLocation.telephone | string | The telephone of the drop-off location. | | dropOffLocation.email | string | The email of the drop-off location. | | returnItems | array | | | returnItems.returnItemStatus | enum |

Status of a return item.

Example: InProgress, Accepted, Rejected

| | returnItems.rejectionReason | string | Reason for the rejection of a return. | | returnItems.returnReasons | array | | | returnReasons.reasonCode | string |

Return reason codes,

Example: WrongItemShipped, Damaged, LateArrival

| | returnReasons.description | string | Description for the return. | | returnReasons.reasonComment | string | The comment the shopper has entered for returning the article. | | returnReasons.isRetailerAtFault | boolean | Flag to identify if the retailer was at fault for the return. | | returnReasons.suppliedBy | integer |

Who supplied the return.

Example: Shopper, CustomerService

| | returnItems.id | guid | Unique ESW specific identifier for the return item. | | returnItems.productCode | string | The Retailer's unique identification code or SKU for the order item. | | returnItems.lineItemId | string | ID that identifies the line item (optionally sent by retailer). | | returnItems.productDescription | string | Title of the product. | | returnItems.productCustomsDescription | string | Description of the product, including material composition for customs. | | returnItems.countryOfOriginIso | string | Two-letter manufacturing country of origin of the product. | | returnItems.hsCode | string | Harmonized System (HS) code of the product. | | returnItems.weight | object | | | weight.weightTotal | double | Weight of the item. | | weight.weightUnit | string |

Weight unit of the item.

Example: Kg, Lb

| | returnItems.unitPrice | object | | | unitPrice.amount | double | Unit price of the product. | | unitPrice.currency | string | Currency ISO associated with the price of the item. | | returnItems.productImageUrl | string | Image URL associated with the item. | | returnItems.color | string | Item color. | | returnItems.size | string | Item size. | | returnItems.category | string | Item Category such as Furniture, Hardware, HealthBeauty, LuggageBag, etc. | | returnItems.personalized | boolean | Flag to indicate if the item has been personalized. | | returnItems.dangerousGoods | boolean | Flag to indicate if the item is Dangerous/Hazardous. | | returnItems.prohibitedForReturns | boolean |

Flag to indicate if the item should be prohibited for return

It is set to ‘False’ by default, unless it’s been overridden during ingestion.

| | returnItems.shippingInformation | object | Additional shipping information. | | shippingInformation.shippingReference | string | Shipping reference. | | shippingInformation.shippingStatus | string | Current shipping status. | | shippingInformation.statusDate | dateTime | Date-Time in UTC format of when the last status had changed. | | weight.weightTotal | double | Weight of the return order. | | weight.weightUnit | string | Unit associated with the weight of the return order. |
Response | **Response Code** | **Description** | | ----------------- | -------------------------------------------------------------- | | 200 (OK) | The requested return order is successfully found and returned. |
{% code title="Request-Response Example" expandable="true" %} ```json { // sample "id":"GOCAS-5000001604" "orderReference": "123456789", "returnOrderNumber": 5000001604, "createdOn": "2022-04-26T15:37:19.337156Z", "lastUpdated": "2022-04-26T15:37:19.337156Z", "status": "Processed", "returnAdminCentreCode": "RUMDC", "returnsListingsGuid": "fa5a96f6-7267-46bd-87e1-36529b01cc10", "returnType": "Normal", "returnMethod": "Postal", "isPaperlessRoute": true, "paidBy": "Retailer", "carrierIdentifier": "SingPost", "dropOffLocation": { "id": "P73", "type": "Store", "name": "POPStation@Kebun Baru CC", "address1": "216", "address2": "Kebun Baru Community Club", "address3": "Ang Mo Kio Avenue 4", "city": "Singapore", "postcode": "569897", "sortcode": "910891", "region": "North-East", "country": "Singapore", "telephone": "12345678910", "email": "test@email.com" }, "returnItems": [{ "returnItemStatus": "accepted", "rejectionReason": "WrongProduct", "returnReasons": [{ "reasonCode": "WrongItemSent", "description": "Wrong Item Sent", "reasonComment": "Don't like the colour", "isRetailerAtFault": true, "suppliedBy": "Shopper" }], "id": "e497818c-77bc-46e1-8572-d3150588e67c", "productCode": "0607339", "lineItemId": "3", "productDescription": "Nike Black Shoes - shipped", "productCustomsDescription": "shoes", "countryOfOriginIso": "IE", "hsCode": "6211490", "weight": { "weightTotal": 0.1, "weightUnit": "Kg" }, "unitPrice": { "amount": 70.2, "currency": "USD" }, "productImageUrl": "https://static.nike.com/a/images/t_PDP_1728_v1/f_auto,b_rgb:f5f5f5/e0f96ae2-51c2-4052-a28b-4a69b3c18718/wio-8-road-running-shoes-96MgNc.png", "color": "Black", "size": "32", "category": "Shoes", "personalized": true, "dangerousGoods": false, "prohibitedForReturns": false, "shippingInformation": { "shippingReference": "FBA_1636646500B", "shippingStatus": "Shipped", "statusDate": "2022-05-04T09:53:42.844Z" } }], "weight": { "weightTotal": 1.2, "weightUnit": "Kg" }, } ``` {% endcode %} *** ## GET Return (Search) This method can be used to search for return orders using a *date range* and/or *status*. It is important to note that this will only return the records from within the last 30 days. To get the return information send a GET request to {% code expandable="true" %} ```http GET /return-orders?status={status}&startUtc={startUtc}&endUtc={endUtc}&returnType={returnType} ``` {% endcode %} ### Method Parameters
Request Parameters | **Field Name** | **Data Type** | **Required/Optional** | **Description** | | ---------------------------- | ----------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | status | string | Required |

Supplied as query string param
Search for return orders with a specific status.

| |

startUtc

endUtc

|

dateTime

dateTime

Limited to max 30 days

| Optional |

Supplied as query string param
Optional DateTime UTC used as search parameters.

| | returnType |

string

Default: not specified

|

Optional

|

Supplied as query string param
Search for return orders with a specific return type.

Not Specified - retrieve all return orders
Normal - retrieve normal return orders
BlindReturn - retrieve blind return orders
Undeliverable - retrieve undeliverable return orders
EUCoolingOff - retrieve EUCoolingOff return orders

|
Response Parameters | **Field Name** | **Type** | **Description** | | ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | id | string | The Return Order identifier. | | orderReference | string | The Retailer’s unique reference for the order. | | returnOrderNumber | ulong | Return order number. | | createdOn | dateTime | Date-Time in UTC format of when the return was created. | | lastUpdated | dateTime | Date-Time in UTC format of when the return was last updated. | | status | string | Overall status of the return. | | returnAdminCentreCode | string | Returns centre used for the return. | | returnsListingsGuid | guid | Unique GUID for the return order. | | returnType | enum |

Type of return

Example: BlindReturn, Undeliverable, Normal etc.

| | returnMethod | enum |

Method used for shipping the return.

Example: Postal, PUDO, Collections

| | isPaperlessRoute | boolean | Flag to check if the return order sends out QR code for paperless Pick-up/Drop-off. | | paidBy | enum |

The party that paid for the return.

Example: Unpaid, Retailer, Shopper

| | carrierIdentifier | string | Unique identifier of the shipping carrier. | | dropOffLocation | object | | | dropOffLocation.id | string | The ID of the location. | | dropOffLocation.type | enum |

Location type

Example: Store, PUDO

| | dropOffLocation.name | string | The name of the drop-off location. | | dropOffLocation.address1 | string | The first line of the address of the drop-off location. | | dropOffLocation.address2 | string | The second line of the address of the drop-off location. | | dropOffLocation.address3 | string | The third line of the address of the drop-off location. | | ropOffLocation.city | string | The city of the drop-off location. | | dropOffLocation.postcode | string | The postcode of the drop-off location. | | dropOffLocation.sortcode | string | The sort code of the drop-off location. | | dropOffLocation.region | string | The region of the drop-off location. | | dropOffLocation.country | string | The country of the drop-off location. | | dropOffLocation.telephone | string | The telephone of the drop-off location. | | dropOffLocation.email | string | The email of the drop-off location. | | dropOffLocation.longtitude | double | Drop-off Location Longtitude (if available). | | dropOffLocation.latitude | double | Drop-off Location Latitude (if available). | | dropOffLocation.distanceInKms | double | The distance to the drop-offlocation from the request postcode. | | dropOffLocation.carrierCode | string | Unique carrier code for ESW. | | dropOffLocation.carrierServiceRouteId | string | Unique reference for the associated ESW route. | | returnItems | array | | | returnItems.returnItemStatus | enum |

Status of a return item.

Example: InProgress, Accepted, Rejected

| | returnItems.rejectionReason | string | Reason for the rejection of a return. | | returnItems.returnReasons | array | | | returnReasons.reasonCode | string |

Return reason codes,

Example: WrongItemShipped, Damaged, LateArrival

| | returnReasons.description | string | Description for the return. | | returnReasons.reasonComment | string | The comment the shopper has entered for returning the article. | | returnReasons.isRetailerAtFault | boolean | Flag to identify if the retailer was at fault for the return. | | returnReasons.suppliedBy | integer |

Who supplied the return.

Example: Shopper, CustomerService

| | shippingInformation.statusDate | dateTime | Date-Time in UTC format of when the last status had changed. | | weight.weightTotal | double | Weight of the return order. | | weight.weightUnit | string | Unit associated with the weight of the return order. |
Response | **Response Code** | **Description** | | ----------------- | ------------------------------------------------------------------------------------------------- | | 200 (OK) | The requested return order array matching the filter criteria is successfully found and returned. |
{% code title="Request-Response Example" expandable="true" %} ```json [{ // sample "id":"GOCAS-5000001604" "orderReference": "123456789", "returnOrderNumber": 5000001604, "createdOn": "2022-04-26T15:37:19.337156Z", "lastUpdated": "2022-04-26T15:37:19.337156Z", "status": "Processed", "returnAdminCentreCode": "RUMDC", "returnsListingsGuid": "fa5a96f6-7267-46bd-87e1-36529b01cc10", "returnType": "Normal", "returnMethod": "Retailer", "isPaperlessRoute": true, "paidBy": "Retailer", "carrierIdentifier": "SingPost", "dropOffLocation": { "id": "P73", "type": "Store", "name": "POPStation@Kebun Baru CC", "address1": "216", "address2": "Kebun Baru Community Club", "address3": "Ang Mo Kio Avenue 4", "city": "Singapore", "postcode": "569897", "sortcode": "910891", "region": "North-East", "country": "Singapore", "telephone": "12345678910", "email": "test@email.com", "longtitude": 123.123, "latitude": 456.456, "distanceInKms": 19, "carrierCode": "sng.postal", "carrierServiceRouteId": "123-ABC-123" }, "returnItems": [{ "returnItemStatus": "accepted", "rejectionReason": null, "returnReasons": [{ "reasonCode": "WrongItemSent", "description": "Wrong Item Sent", "reasonComment": "Don't like the colour", "isRetailerAtFault": true, "suppliedBy": "Shopper" }], "id": "e497818c-77bc-46e1-8572-d3150588e67c", "productCode": "0607339", "lineItemId": "3", "productDescription": "Nike Black Shoes - shipped", "productCustomsDescription": "shoes", "countryOfOriginIso": "IE", "hsCode": "6211490", "weight": { "weightTotal": 0.1, "weightUnit": "Kg" }, "unitPrice": { "amount": 70.2, "currency": "USD" }, "productImageUrl": "https://static.nike.com/a/images/t_PDP_1728_v1/f_auto,b_rgb:f5f5f5/e0f96ae2-51c2-4052-a28b-4a69b3c18718/wio-8-road-running-shoes-96MgNc.png", "color": "Black", "size": "32", "category": "Shoes", "personalized": true, "dangerousGoods": false, "prohibitedForReturns": false, "shippingInformation": { "shippingReference": "FBA_1636646500B", "shippingStatus": "Shipped", "statusDate": "2022-05-04T09:53:42.844Z" } }], "weight": { "weightTotal": 1.2, "weightUnit": "Kg" }, }] ``` {% endcode %} *** ## POST- Create Lite Return The Create Lite Return Order endpoint can be used to create a Lite Return Order in the Returns Platform via a lite retailer integration. To create lite return send a POST request to `POST /{tenantCode}/lite-return-orders`
Request Body | Method | POST | | ------ | -------------------------------- | | Path | /{tenantCode}/lite-return-orders | 
{
  "orderReference": "REF4181811",
  "returnMethod": 0,
  "paidBy": 0,
  "carrierIdentifier": "EVRI",
  "isPaperlessRoute": true,
  "cultureLanguageIso": "en-IE",
  "dropOffLocation": {
      "id": "1234567",
      "type": 0,
      "name": "PostOffice",
      "address1": "Address1",
      "address2": "Address2",
      "address3": "Address3",
      "city": "City",
      "postcode": "1234 567",
      "sortcode": "123",
      "region": "Region",
      "country": "Country",
      "telephone": "12345678901",
      "email": "email@email.com",
      "openingTimesDescription": "24Hrs",
      "openingTimes": [
        {
          "day": "Monday",
          "opens": "09:00",
          "closes": "21:00"
        }
      ]
  },
  "contactInformation": {
    "firstName": "First",
    "lastName": "Last",
    "address1": "Address1",
    "address2": "Address2",
    "city": "City",
    "postalCode": "1234 567",
    "countryIso": "GB",
    "email": "email@email.com",
    "telephone": "12345678901"
  },
  "returnItems": [
    {
      "productCode": "Product1",
      "quantity": 2,
      "reasonCode": "DoNotLike",
      "unitPrice": {
        "amount": 12.50,
        "currency": "GBP"
      }
    }
  ],
  "returnAdminCentreCodeOverride": "IRLDC",
  "IncludeLabelInResponse": true,
  "IncludeInstructions": true
}
Response Body | Response Code | 201 Created | | ------------- | ------------------------------------------- | | Description | Successfully created the lite return order. | ``` { // sample "orderReference": "123546", "returnOrderNumber": "3000125648", "returnsListingGuid": "0000-0000-0000-0000", "returnMethod": "PUDO", "paidBy": "Retailer", "carrierIdentifier": "ABC123", "isPaperlessRoute": true, "dropOffLocation": { "id": "Identifier12", "type": 0, "name": "Location", "address1": "Address1", "address2": "Address2", "address3": "Address3", "city": "City", "postcode": "Postcode", "sortcode": "Sortcode", "region": "Region", "country": "Country", "telephone": "0441521854845", "email": "email@email.com, "openingTimesDescription": "24Hrs, "openingTimes": [ { "day": "Monday", "opens": "09:00", "closes": "18:00" } ] }, "returnItems": [ { "productCode": "P1", "quantity": 2, "reasonCode": "DoNotLike", "unitPrice": { "amount": 12.50, "currency": "GBP" } } ], "returnAdminCentreCode": "IRLDC", "contentType": "application/pdf", "label": "PHN2ZyB4bWxucz0iaHR0cDo..." } ```
### Method Parameters
Request Parameters | Request Fields | | | | | ----------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | **Field Name** | **Type** | **Validation** | **Description** | | OrderReference | string |

Required

Max 30 characters

| The OrderReference of Order to be associated with Return | | ReturnMethod | enum |

Required

Is valid enum value:

Postal = 1

PUDO = 2

Collections = 3

Store = 4

| The return method of the intended shipping route | | PaidBy | enum |

Required

Is valid enum value:

Unpaid = 1

Retailer = 2

Shopper = 3

| The party that paid for the return | | CarrierIdentifier | string | | Unique identifier of the Carrier | | IsPaperlessRoute | boolean | | Defines whether the route is paperless or not | | CultureLanguageIso | string |

Required

Must be valid country ISO

| Country ISO of Return | | DropOffLocation | DropOffLocationDto | Must be null when ReturnMethod is not PUDO or Store | Drop Off Location for the Return | | [DropOffLocation.Id](http://DropOffLocation.Id) | string | | Id of drop off location | | DropOffLocation.Type | enum |

Required

Is valid enum value:

Store = 1

Pudo = 2

| Drop off location type | | DropOffLocation.Name | string | Max 100 characters | Name of drop off location | | DropOffLocation.Address1 | string | Max 150 characters | Line 1 of drop off location address | | DropOffLocation.Address2 | string | Max 150 characters | Line 2 of drop off location address | | DropOffLocation.Address3 | string | Max 150 characters | Line 3 of drop off location address | | DropOffLocation.City | string |

Not null

Max 150 characters

| City of drop off location | | DropOffLocation.Postcode | string | Max 50 characters | Postcode of drop off location | | DropOffLocation.Sortcode | string | Max 10 characters | Sortcode of drop off location | | DropOffLocation.Region | string | Max 50 characters | Region of drop off location | | DropOffLocation.Country | string |

Required

Max 50 characters

| Country of drop off location | | DropOffLocation.Telephone | string | Max 150 characters | Contact number for drop off location | | DropOffLocation.Email | string | | Contact email of drop off location | | DropOffLocation.OpeningTimesDescription | string | | Description of opening times for drop off location | | DropOffLocation.OpeningTimes | List\ | | List of opening times by day | | DropOffLocation.OpeningTimes.Day | string |

Required

Must be valid day of the week

| Day of the week | | DropOffLocation.OpeningTimes.Opens | string | Required | Opening time for the given day | | DropOffLocation.OpeningTimes.Closes | string | Required | Closing time for the given day | | ContactInformation | LiteReturnContactInformationDto | Not null | Customer contact information | | ContactInformation.FirstName | string |

Required

Max 70 characters

| Customer first name | | ContactInformation.LastName | string |

Required

Max 70 characters

| Customer last name | | ContactInformation.Address1 | string |

Required

Max 150 characters

| First line of customer address | | ContactInformation.Address2 | string | Max 150 characters | Second line of customer address | | ContactInformation.City | string |

Required

Max 150 characters

| Customer’s city | | ContactInformation.PostalCode | string | Max 50 characters | Post code of customer’s address | | ContactInformation.CountryIso | string |

Required

Must be valid Country ISO

| Customer’s country | | ContactInformation.Email | string |

Required

Valid email format

Max 100 characters

| Contact email address for customer | | ContactInformation.Telephone | string | Max 50 characters | Contact telephone number for customer | | ReturnItems | List\ | Required | Items to be returned | | ReturnItems.ProductCode | string |

Required

Max 50 characters

| Item’s product code | | ReturnItems.Quantity | int |

Greater than 0

Less than or equal to 2147483647

| Number of copies of this item to be returned | | ReturnItems.ReasonCode | string | | Reason code for why item is being returned | | ReturnItems.UnitPrice | UnitPriceDto | Required | Price information of return item | | ReturnItems.UnitPrice.Amount | Decimal |

Not null

Greater than 0

| Value of return item | | ReturnItems.UnitPrice.Currency | string |

Required

Must be valid currency ISO

| Currency of return item value | | ReturnAdminCentreCodeOverride | string | Max 20 characters | Code to identify return centre to override default value | | IncludeLabelInResponse | boolean | | True indicates the response will contain the return label. False indicates the return label should be obtained asynchronously. | | IncludeInstructions | boolean | | Indicates whether instructions should be included with the return label document. |
Response Parameters | Response Fields | | | | ----------------------------------------------- | ------------- | -------------------------------------------------------------- | | **Field Name** | **Type** | **Description** | | OrderReference | string | Unique identifier of the order | | ReturnOrderNumber | string | Unique identifier of the return | | ReturnsListingGuid | Guid | GUID of returns listing | | ReturnMethod | string | Method of returning | | PaidBy | string | Party that paid for the return | | CarrierIdentifier | string | Unique identifier of the carrier | | IsPaperlessRoute | boolean | Shows whether a route is paperless or not | | DropOffLocation | Object | Location of where to drop off return | | [DropOffLocation.Id](http://DropOffLocation.Id) | string | Identifier of drop off location | | DropOffLocation.Type | enum | Drop off location type | | DropOffLocation.Name | string | Name of drop off location | | DropOffLocation.Address1 | string | First line of drop off location address | | DropOffLocation.Address2 | string | Second line of drop off location address | | DropOffLocation.Address3 | string | Third line of drop off location address | | DropOffLocation.City | string | City of drop off location | | DropOffLocation.Postcode | string | Postcode of drop off location | | DropOffLocation.Sortcode | string | Sortcode of drop off location | | DropOffLocation.Region | string | Region of drop off location | | DropOffLocation.Country | string | Country of drop off location | | DropOffLocation.Telephone | string | Contact telephone number of drop off location | | DropOffLocation.Email | string | Contact email address of drop off location | | DropOffLocation.OpeningTimesDescription | string | Description of drop off location opening times | | DropOffLocation.OpeningTimes | List\ | List of opening days and times of drop off location | | DropOffLocation.OpeningTimes.Day | string | Day of the week when drop off location is open | | DropOffLocation.OpeningTimes.Opens | string | Time drop off location opens on that day | | DropOffLocation.OpeningTimes.Closes | string | Time drop off location closes on that day | | ReturnItems | List\ | Items that were returned | | ReturnItems.ProductCode | string | Product code of returned item | | ReturnItems.Quantity | int | Number of this item that was returned | | ReturnItems.ReasonCode | string | Reason code for why item was returned | | ReturnItems.UnitPrice | Object | Pricing information of returned item | | ReturnItems.UnitPrice.Amount | decimal | Value of returned item | | ReturnItems.UnitPrice.Currency | string | Currency of returned item’s value | | ReturnAdminCentreCode | string | Admin centre code that return was created against | | ContentType | string | Return document MIME type that can used to render the document | | Label | string | Base64 string document content | ## POST- Create Return The create return order endpoint can be used to create a *Return Order* in the returns platform. To create return send a POST request to /orders/{orderReference}/return-orders ### Method Parameters
Request Parameters | **Field Name** | **Data Type** | **Required/Optional** | **Description** | | --------------------------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | orderReference |

string

(Max 30 char)

|

Required

|

The Retailer’s unique reference for the order.

This is case-insensitive.

| | contactEmailAddress |

string

(Max 100 char)

|

Required

| Email from Order - used for validation. | | returnMethod | enum | Required |

Method used for shipping the return.

Example: Postal, PUDO, Collections

| | paidBy | enum |

Required

|

The party that paid for the return.

Example: Unpaid, Retailer, Shopper

| | carrierIdentifier | string | Optional |

The carrier identifier.

Example: RoyalMail

  • If provided, the returnMethod, paidBy and carrierIdentifier must refer to an available route.
  • When not provided, a carrier will be selected based on returnMethod and paidBy where possible. Where multiple carriers are found, a validation error response will indicate this.
| | isPaperlessRoute | boolean | Optional (default to false) | Flag to indicate whether the return shipping route is paperless or not. | | cultureLanguageIso | string | Required | Language culture ISO code. | | dropOffLocation | object |

Optional

Validated against Return Method being set to PUDO otherwise Optional

| Object with a dropOffLocation which consists of address info , contact info, and opening times. | | [dropOffLocation.id](http://dropOffLocation.id) | string | Required | The ID for the location | | dropOffLocation.type | enum | Required |

Location type - see enum/locationType

Example: Store, PUDO

| | [dropOffLocation.name](http://dropOffLocation.name) | string | Required | The name of the location. | | dropOffLocation.address1 |

string

(Max 150 char)

| Required | The first line of the address of the location. | | dropOffLocation.address2 |

string

(Max 150 char)

| Optional | The second line of the address of the location. | | dropOffLocation.address3 |

string

(Max 150 char)

| Optional | The third line of the address of the location. | | dropOffLocation.city |

string

(Max 150 char)

| Optional (cant be null) | The city of the location. | | dropOffLocation.postcode |

string

(Max 50 char)

| Optional | The postcode of the location. | | dropOffLocation.sortcode |

string

(Max 10 char)

| Optional | The sortcode of the location. | | dropOffLocation.region |

string

(Max 50 char)

|

Optional

| The region of the location. | | dropOffLocation.country |

string

(Max 50 char)

|

Optional

| The country of the location. | | returnItems | array | Required (at least one) | Array of Return Items. | | returnItems.Id | guid |

Required

Required if ProductCode is not set

| Unique ESW ID of article. | | returnItems.reasonCode | string | Required |

Valid Return reason codes.

Example: "WrongItemShipped", "Damaged", "LateArrival"

| | returnItems.reasonComment |

string

(Max 100 char)

|

Optional

| Custom comment about a return. | | returnItems.lineItemId | string |

Required

ProductCode, with optional line item ID, is required if ID is not set.

| ID that identifies the line item. | | returnItems.productCode |

string

(Max 50 char)

|

Required

ProductCode, with optional line item ID is required if ID is not set.

|

The Retailer's unique identification code or SKU for the order item.

When ProductCode, Id, LineItemId are all provided - they must match to the same item.

| | weight.weightTotal | double | Optional | Weight of the package. | | weight.weightUnit | enum | Optional |

Unit associated with the weight of the package.

Example: Kg, Lb

| **Request Parameters For Undeliverable Returns Order** | **Field Name** | **Data Type** | **Required/Optional** | **Description** | | ------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | orderReference |

string

(Max 30 chars)

|

Required

|

Supplied in URL
The Retailer’s unique reference for the order.

Case-insensitive.

| | contactEmailAddress |

string

(Max 100 chars)

| Required | Email from Order - used for validation | | cultureLanguageIso | string | Required | Language culture iso | | returnType | enum | Required | Use ‘Undeliverable’ | | shippingReference |

string

(Max 50 chars)

|

Required

Required when returnType is “Undeliverable” and both carrierReference and barcodeReference are not provided

|

The retailer's unique barcode reference for the package in which the item was shipped.

The Undeliverable return order will contain the order items matching the provided shippingReference, if provided.

| | carrierReference |

string

(Max 50 chars)

| Optional |

The carrier’s unique shipping reference for the package in which the item was shipped.

The Undeliverable return order will contain the order items matching the provided carrierReference, if provided.

| | barcodeReference |

string

(Max 50 chars)

| Optional |

The retailer's unique barcode reference for the package in which the item was shipped.

The Undeliverable return order will contain the order items matching the provided barcodeReference, if provided.

| | weight.weightTotal | double | Optional | Weight of the undeliverable package | | weight.weightUnit | enum | Optional |

The unit of the weight of the undeliverable package.

Example: Kg, Lb

|
Response Parameters | **Field Name** | **Data Type** | **Description** | | ------------------------------ | ------------- | ------------------------------------------------------------------------------------ | | returnOrderNumber | ulong | Return order number | | returnType | enum |

Type of return.

BlindReturn, Undeliverable, Normal etc.

| | returnMethod | enum |

Method used for shipping the return.

Postal, PUDO, Collections

| | paidBy | enum |

The party that paid for the return.

Unpaid, Retailer, Shopper

| | carrierIdentifier | string | The ID of the carrier | | isPaperlessRoute | boolean | Indicates whether the return was created with a paperless route or not. | | dropOffLocation | object | Drop Off Location. | | dropOffLocation.id | string | The ID of the location. | | dropOffLocation.type | enum |

Carrier service type used.

Post, PUDO

| | dropOffLocation.name | string | The name of the location. | | dropOffLocation.address1 | string | The first line of the address of the location. | | dropOffLocation.address2 | string | The second line of the address of the location. | | dropOffLocation.address3 | string | The third line of the address of the location. | | dropOffLocation.city | string | The city of the location. | | dropOffLocation.postcode | string | The postcode of the location. | | dropOffLocation.sortcode | string | The sortcode of the location. | | dropOffLocation.region | string | The region of the location. | | dropOffLocation.country | string | The country of the location. | | returnItems | array | This is the display string for the closing time for the specific day. | | returnItems.Id | guid | Unique ESW ID associated with the article. | | returnItems.lineItemId | string | ID that identifies the line item (optionally sent by retailer) | | returnItems.productCode | string | The Retailer's unique identification code or SKU for the order item. | | returnItems.productDescription | string | Title of the product. | | returnItems.productImageUrl | string | Image URL of the item. | | returnItems.color | string | Product colour. | | returnItems.size | string | Product size. | | returnItems.category | string | Product category. | | returnItems.reasonCode | string | Return reason code. | | returnItems.reasonComment | string | Comment with the return reason. |
Response | **Response Code** | **Description** | | ----------------- | -------------------------------------- | | 201 (Created) | Successfully created the return order. | | 400 (Bad Request) | Could not process the request. |
{% code title="Request-Response Example" expandable="true" %} ```json { // sample "returnsListingsGuid": "4c071f76-e27b-4291-a29h1", "returnOrderNumber": 500000000342342343, "returnType": "Normal", "returnMethod": "Postal", "paidBy": "Unpaid", "carrierIdentifier": "Royal Mail", "isPaperlessRoute": "true", "dropOffLocation": { "id": "P73", "type": "Pudo", "name": "POPStation@Kebun Baru CC", "address1": "216", "address2": "Kebun Baru Community Club", "address3": "Ang Mo Kio Avenue 4", "city": "Singapore", "postcode": "569897", "sortcode": "910891", "region": "North-East", "country": "Singapore" }, "returnitems": [ { "id": "0013db57-885d-462b-a24f-80312a9g3207", "lineItemid": "1", "productCode": "112233", "productDescription":"Red scarf", "productImageUrl": "https://image.com", "color": "Red", "size": "L", "category": "Fashion", "reasonCode": "Defective", "reasonComment": "Broken glass" }, { "id": "8014db57-785d-462b-a24f-80312a9g3207", "lineItemid": "1", "productCode": "112234", "productImageUrl": "https://image.com", "color": "Red", "size": "L", "category": "Fashion", "reasonCode": "LateArrival", "reasonComment": "The product arrived too late" } ] } ``` {% endcode %} *** ## PUT- Update Return The *Update Return Order* endpoint can be used to update some parts of a Return Order in the Return Platform. To create return send a PUT request to /orders/{orderReference}/return-orders/{returnOrderNumber} ### Method Parameters
Request Parameters | **Field Name** | **Type** | **Required/Optional** | **Description** | | --------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | orderReference |

string

(Max 30 chars)

| Required |

Supplied in URL
The Retailer’s unique reference for the order.

Case-insensitive.

| | returnOrderNumber | ulong | Required |

Supplied in URL
Return platform return order number

| | status | enum | Required |

New return order status.

Possible values:

  • Created
  • Received
  • OnHold
  • Released
  • Processed
  • AddedToManifest
  • SentToRetailer
  • ReceivedByRetailer
  • RemovedFromManifest
  • Cancelled
  • Refunded
| | statusReason | string |

Required

Required if the status is “OnHold”. It is optional otherwise.

| The reason for the status update. | | returnItems | array |

Required

Required if the status is “Processed”, otherwise Optional.

|

Array of Return Items

When Status is “Processed” all return items must be provided in the request with associated status and, when applicable, with rejection reason.

| | [returnItems.Id](http://returnItems.Id) | guid |

Required

Required if ProductCode is not set.

| Unique ESW ID associated with the article. | | returnItems.lineItemId | string |

Required

ProductCode, with optional line item id, is required if ID is not set.

| ID that identifies the line item. | | returnItems.productCode |

string

(Max 50 char)

|

Required

ProductCode, with optional line item ID, is required if ID is not set.

|

The Retailer's unique identification code or SKU for the order item.

When ProductCode, ID, LineItemId are all provided - they must match to the same item.

| | returnItems.returnItemStatus | enum | Required |

Return item status.

Possible values:

  • Accepted
  • Rejected
| | returnItems.rejectionReason | string |

Required

Required if ReturnItemStatus is “Rejected”, otherwise Optional.

|

The reason for rejecting the return item.

Valid rejection reason, for example, “ArticleNotIncluded"

| | returnItems.reasonCodeOverride | string | Optional |

Value to replace the original shopper supplied return reason.

For example, "WrongItemShipped", "Damaged", "LateArrival"

| | returnItems.reasonCode | string | Optional |

Return order item reason code.

If not provided; defaults to “NoReasonCodeSelected-v3”

| | weight.weightTotal | double | Optional | Weight of the package | | weight.weightUnit | enum | Optional |

Unit associated with the weight of the package.

Example: Kg, Lb

|
Response Parameters | **Field Name** | **Type** | **Description** | | --------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | id | string | The Return Order identifier. | | orderReference | string | The Retailer’s unique reference for the order. | | returnOrderNumber | ulong | Return order number. | | createdOn | dateTime | Date-Time in UTC format of when the return was created. | | lastUpdated | dateTime | Date-Time in UTC format of when the return was last updated. | | status | string | Overall status of the return. | | returnAdminCentreCode | string | Returns centre used for the return. | | returnsListingsGuid | guid | Unique GUID for the return order. | | returnType | enum |

Type of return

Example: BlindReturn, Undeliverable, Normal etc.

| | returnMethod | enum |

Method used for shipping the return.

Example: Postal, PUDO, Collections

| | isPaperlessRoute | boolean | Flag to check if the return order sends out QR code for paperless Pick-up/Drop-off. | | paidBy | enum |

The party that paid for the return.

Example: Unpaid, Retailer, Shopper

| | carrierIdentifier | string | Unique identifier of the shipping carrier. | | dropOffLocation | object | | | [dropOffLocation.id](http://dropOffLocation.id) | string | The ID of the location. | | dropOffLocation.type | enum |

Location type

Example: Store, PUDO

| | [dropOffLocation.name](http://dropOffLocation.name) | string | The name of the drop-off location. | | dropOffLocation.address1 | string | The first line of the address of the drop-off location. | | dropOffLocation.address2 | string | The second line of the address of the drop-off location. | | dropOffLocation.address3 | string | The third line of the address of the drop-off location. | | ropOffLocation.city | string | The city of the drop-off location. | | dropOffLocation.postcode | string | The postcode of the drop-off location. | | dropOffLocation.sortcode | string | The sort code of the drop-off location. | | dropOffLocation.region | string | The region of the drop-off location. | | dropOffLocation.country | string | The country of the drop-off location. | | dropOffLocation.telephone | string | The telephone of the drop-off location. | | dropOffLocation.email | string | The email of the drop-off location. | | dropOffLocation.longtitude | double | Drop-off Location Longtitude (if available). | | dropOffLocation.latitude | double | Drop-off Location Latitude (if available). | | dropOffLocation.distanceInKms | double | The distance to the drop-offlocation from the request postcode. | | dropOffLocation.carrierCode | string | Unique carrier code for ESW. | | dropOffLocation.carrierServiceRouteId | string | Unique reference for the associated ESW route. | | returnItems | array | | | returnItems.returnItemStatus | enum |

Status of a return item.

Example: InProgress, Accepted, Rejected

| | returnItems.rejectionReason | string | Reason for the rejection of a return. | | returnItems.returnReasons | array | | | returnReasons.reasonCode | string |

Return reason codes,

Example: WrongItemShipped, Damaged, LateArrival

| | returnReasons.description | string | Description for the return. | | returnReasons.reasonComment | string | The comment the shopper has entered for returning the article. | | returnReasons.isRetailerAtFault | boolean | Flag to identify if the retailer was at fault for the return. | | returnReasons.suppliedBy | integer |

Who supplied the return.

Example: Shopper, CustomerService

| | returnItems.id | guid | Unique ESW identifier for the return item. | | returnItems.productCode | string | The Retailer's unique identification code or SKU for the order item | | returnItems.lineItemId | string | ID that identifies the line item (optionally sent by retailer) | | returnItems.productDescription | string | Title of the product. | | returnItems.productCustomsDescription | string | Description of the product, including material composition for customs. | | returnItems.countryOfOriginIso | string | Two-letter manufacturing country of origin of the product. | | returnItems.hsCode | string | Harmonized System (HS) code of the product. | | returnItems.weight | object | | | weight.weightTotal | double | Weight of the item | | weight.weightUnit | string |

Weight unit of the item.

Example: Kg, Lb

| | returnItems.unitPrice | object | | | unitPrice.amount | double | Unit price of the product. | | unitPrice.currency | string | Currency ISO associated with the price of the item. | | returnItems.productImageUrl | string | Image URL of the item. | | returnItems.color | string | Item color. | | returnItems.size | string | Item size. | | returnItems.category | string | Item Category such as Furniture, Hardware, HealthBeauty, LuggageBag, etc. | | returnItems.personalized | boolean | Flag to indicate if the item has been personalized. | | returnItems.dangerousGoods | boolean | Flag to indicate if the item is Dangerous/Hazardous. | | returnItems.prohibitedForReturns | boolean |

Flag to indicate if the item should be prohibited for return

Defaults to ‘False’ unless it is overridden during ingestion.

| | returnItems.shippingInformation | object | Additional shipping information. | | shippingInformation.shippingReference | string | Shipping reference. | | shippingInformation.shippingStatus | string | Current shipping status. | | shippingInformation.statusDate | dateTime | Date-Time in UTC format of when the last status change occurred. |
Response | **Response Code** | **Description** | | ----------------- | -------------------------------------- | | 200 (Ok) | Successfully updated the return order. | | 400 (Bad Request) | Could not process the request. |
{% code title="Request-Response Example" expandable="true" %} ```json { // sample "id":"GOCAS-5000001604" "orderReference": "123456789", "returnOrderNumber": 5000001604, "createdOn": "2022-04-26T15:37:19.337156Z", "lastUpdated": "2022-04-26T15:37:19.337156Z", "status": "Processed", "returnAdminCentreCode": "RUMDC", "returnsListingsGuid": "fa5a96f6-7267-46bd-87e1-36529b01cc10", "returnType": "Normal", "returnMethod": "Postal", "isPaperlessRoute": true, "paidBy": "Retailer", "carrierIdentifier": "SingPost", "dropOffLocation": { "id": "P73", "type": "Store", "name": "POPStation@Kebun Baru CC", "address1": "216", "address2": "Kebun Baru Community Club", "address3": "Ang Mo Kio Avenue 4", "city": "Singapore", "postcode": "569897", "sortcode": "910891", "region": "North-East", "country": "Singapore", "telephone": "12345678910", "email": "test@email.com", "longtitude": 12345.123, "latitude": 123435.123, "distanceInKms": 20, "carrierCode": "sng-post.postal", "carrierServiceRouteId": "abc1-12345" }, "returnItems": [{ "returnItemStatus": "accepted", "rejectionReason": "WrongProduct", "returnReasons": [{ "reasonCode": "WrongItemSent", "description": "Wrong Item Sent", "reasonComment": "Don't like the colour", "isRetailerAtFault": true, "suppliedBy": "Shopper" }], "id": "e497818c-77bc-46e1-8572-d3150588e67c", "productCode": "0607339", "lineItemId": "3", "productDescription": "Nike Black Shoes - shipped", "productCustomsDescription": "shoes", "countryOfOriginIso": "IE", "hsCode": "6211490", "weight": { "weightTotal": 0.1, "weightUnit": "Kg" }, "unitPrice": { "amount": 70.2, "currency": "USD" }, "productImageUrl": "https://static.nike.com/a/images/t_PDP_1728_v1/f_auto,b_rgb:f5f5f5/e0f96ae2-51c2-4052-a28b-4a69b3c18718/wio-8-road-running-shoes-96MgNc.png", "color": "Black", "size": "32", "category": "Shoes", "personalized": true, "dangerousGoods": false, "prohibitedForReturns": false, "shippingInformation": { "shippingReference": "FBA_1636646500B", "shippingStatus": "Shipped", "statusDate": "2022-05-04T09:53:42.844Z" } }] } ``` {% endcode %} *** ## GET- Shipping Documents This endpoint can be used to gather shipping documents that have been generated for a return order. Shipping documents are generated in an asynchronous manner. Therefore, the documentStatus field will be "Processing" until all documents have been fully generated and go into the status "Ready". To create return send a GET request to /return-orders/{returnOrderNumber}/{documentType} ### Method Parameters
Request Parameters | **Field Name** | **Data Type** | **Required/Optional** | **Description** | | ----------------- | ------------- | --------------------- | --------------------------------------------------------------------------- | | returnOrderNumber | ulong | Required | The return order number from the returns platform. | | documentType | enum |

Required

|

Document Type to return.

ReturnLabel or LastMileLabel

|
Response Parameters | **Field Name** | **Type** | **Description** | | ------------------------ | -------- | ------------------------------------------------------------------------------------------ | | orderReference | string | The retailer’s unique reference for an order. | | returnOrderNumber | ulong | The return order number from the returns platform. | | contentType | string | Return document content type that can be used to render the document. | | documentStatus | enum |

Status of the document generation

Example: Processing, Ready, Failed

| | label | string | Base64 string document content. | | cultureLanguageIso | string | Culture language ISO code. | | documentId | guid | Unique identifier for a return document. | | documentType | enum |

Type of document.

Example: ReturnLabel, LastMileLabel

| | carrierId | string | Unique identifier of the shipping carrier. | | carrierName | string | Shipping carrier name. | | carrierReference | string | Carrier shipment reference (if applicable). | | carrierTrackingReference | string | Carrier shipment tracking reference (if applicable). |
Response | **Response Code** | **Description** | | ----------------- | ---------------------------------------------------------------- | | 200 (Ok) | Successfully retrieved shipping documents from the return order. |
{% code title="Request-Response Example" expandable="true" %} ```json { "orderReference": "2123456789", "returnOrderNumber": "5000012345", "contentType": "pdf", "documentStatus": "Processing", "label": "PHN2ZyB4bWxucz0iaHR0cDo...", "cultureLanguageIso": "fr-FR", "documentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "documentType": "ReturnLabel", "carrierInfoDetails": { "carrierId": "US-US-Inbound-UPSMI-PUDO", "carrierName": "UPS MI", "carrierReference": "4206000792023909899863543400002364", "carrierTrackingReference": "4206000792023909899863543400002364" } } ``` {% endcode %} *** ## GET Return Methods ### Method Parameters This endpoint can be used to search for the available shipping methods for a return.
Request Parameters | **Field Name** | **Data Type** | **Validation** | **Description** | | ---------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | orderReference |

string

(Max 30 chars)

| Required |

The Retailer’s unique reference for the order.

This is case-insensitive.

| | orderItems | array | | Array of return items requested. | | orderItems.Id | guid |

· Required

ID is required if ProductCode is not set.

| Unique ESW ID associated with the article. | | orderItems.productCode |

string

(Max 50 chars)

|

Required

ProductCode, with optional LineItemId, is required if Id is not set

|

The Retailer's unique identification code or SKU for the order item.

When ProductCode, ID, lineItemId are all provided, then they must match to the same item.

| | orderItems.lineItemId | string |

Required

ProductCode, with optional line item ID, is required if ID is not set.

| ID that identifies the line item. |
Response Parameters | **Field Name** | **Type** | **Description** | | ----------------------------------------- | -------- | --------------------------------------------------------------------------------------------- | | orderReference | string | The Retailer’s unique reference for order | | originCountryIso | string | Two letter country ISO of origin country | | destinationCountryIso | string | Two letter country ISO of destination country | | selectedReturnAdminCentreCode | string | Selected return centre code | | returnMethods | array | The list of available return methods | | returnMethods.returnMethod | enum |

Method used for shipping the return.

Example: Postal, PUDO, Collections

| | returnMethods.paidBy | enum |

The party that paid for the return.

Example: Unpaid, Retailer, Shopper

| | returnMethods.carrierServiceRoute | object | | | carrierServiceRoute.carrierServiceRouteId | string | The unique identifier of the route. | | carrierServiceRoute.eswCarrierIdentifier | string | The unique identifier of the carrier. | | carrierServiceRoute.carrierName | string | The name of the carrier. | | carrierServiceRoute.serviceType | enum |

Carrier service type used.

Example: Post, PUDO

| | carrierServiceRoute.carrierServiceCode | string | Code that’s passed to the carrier for the service type. | | carrierServiceRoute.isPaperlessRoute | boolean | Flag to indicate if the return method is paperless. |
Response | **Response Code** | **Description** | | ----------------- | ------------------------------------------------ | | 200 (Ok) | Successfully retrieved available return methods. |
{% code title="Request-Response Example" expandable="true" %} ```json { "orderReference": "123456789", "originCountryIso": "GB", "destinationCountryIso": "FR", "selectedReturnAdminCentreCode": "ASEFR", "returnMethods": [{ "returnMethod": "Postal", "paidBy": "Retailer", "carrierServiceRoute": { "carrierServiceRouteId": "GB_FR", "eswCarrierIdentifier": "Asendia", "carrierName": "DHL", "serviceType": "Post", "carrierServiceCode": "WPX", "isPaperlessRoute": "true" }] } ``` {% endcode %} *** --- # 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/returns-api-v3.0/methods/return-methods.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.