> 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/retrieving-and-listing-return-orders.md).

# Retrieving and Listing Return Orders

After a return order is created, two endpoints allow you to read its current state: a single-order <mark style="color:$success;">`GET`</mark> for the full detail of a specific return, and a list <mark style="color:$success;">`GET`</mark> for searching and filtering across all returns for a tenant. Both are essential for building operational dashboards, polling for status changes, and feeding return data into downstream systems.

***

{% stepper %}
{% step %}

### Retrieval Endpoints

| Endpoint                                                                      | Use when                                                                                                                   |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `GET /{identifier}/orders/{orderReference}/return-orders/{returnOrderNumber}` | You know the specific return order number and want the full detail of that return                                          |
| `GET /{identifier}/return-orders`                                             | You want to search or list returns by status, date range, or return type — for dashboards, batch processing, or monitoring |

***

{% endstep %}

{% step %}

### Retrieving a Specific Return Order

```http
GET /{identifier}/orders/{orderReference}/return-orders/{returnOrderNumber}
Authorization: Bearer <token>
```

**Path parameters:**

| Parameter             | Description                                                                           |
| --------------------- | ------------------------------------------------------------------------------------- |
| `{identifier}`        | Your tenant identifier                                                                |
| `{orderReference}`    | The original outbound order reference                                                 |
| `{returnOrderNumber}` | The return order number from the `POST /return-orders` response — e.g. `"5000002303"` |

**Example:**

```http
GET /MYBRAND/orders/ORD-2024-78542/return-orders/5000002303
Authorization: Bearer <token>
```

**Response:** `200 OK` with `GetReturnOrderWebResponse`

***

{% endstep %}

{% step %}

### `GetReturnOrderWebResponse`&#x20;

{% code expandable="true" %}

```json
{
  "id": "MYBRAND-5000002303",
  "status": "Received",
  "returnAdminCentreCode": "IEDUB",
  "returnsListingsGuid": "4039312f-868d-4c64-ae6a-b6c9be74d07b",
  "returnType": "Normal",
  "returnOrderNumber": "5000002303",
  "returnMethod": "Postal",
  "isPaperlessRoute": false,
  "paidBy": "Retailer",
  "carrierIdentifier": "Ascendia",
  "dropOffLocation": null,
  "orderReference": "ORD-2024-78542",
  "createdOn": "2024-11-10T09:20:51.172Z",
  "lastUpdated": "2024-11-14T11:45:00.000Z",
  "returnItems": [ ... ],
  "weight": {
    "weightTotal": 0.3,
    "weightUnit": "KG"
  }
}
```

{% endcode %}

<details>

<summary>Top-level field reference</summary>

| Field                   | Type           | Description                                                                              |
| ----------------------- | -------------- | ---------------------------------------------------------------------------------------- |
| `id`                    | string         | Internal ESW identifier — typically `{tenantCode}-{returnOrderNumber}`                   |
| `status`                | enum           | Current `ReturnOrderStatus` — see Tutorial 12 for all 11 values                          |
| `returnAdminCentreCode` | string         | The ESW warehouse that will receive/has received this return — e.g. `"IEDUB"`, `"AUCOW"` |
| `returnsListingsGuid`   | UUID           | ESW's listings system reference — store for audit                                        |
| `returnType`            | enum           | `Normal`, `Undeliverable`, `BlindReturn`, or `EUCoolingOff`                              |
| `returnOrderNumber`     | string         | The return order number — the primary identifier for this return                         |
| `returnMethod`          | enum           | `Postal`, `PUDO`, or `Collections`                                                       |
| `isPaperlessRoute`      | boolean        | Whether this return uses paperless label flow                                            |
| `paidBy`                | string         | Who paid the return shipping: `"Retailer"`, `"Shopper"`, or `"Unpaid"`                   |
| `carrierIdentifier`     | string         | ESW's carrier identifier for this return                                                 |
| `dropOffLocation`       | object or null | PUDO location details if applicable                                                      |
| `orderReference`        | string         | The original outbound order reference                                                    |
| `createdOn`             | ISO 8601 UTC   | When the return order was created                                                        |
| `lastUpdated`           | ISO 8601 UTC   | When the return order was last modified — use for change detection                       |
| `returnItems`           | array          | Per-item detail — see Step 4                                                             |
| `weight`                | object         | Return parcel weight                                                                     |

</details>

#### Key fields for integration

* **`status`** — poll this to detect state changes (e.g. `Created` → `Received`)
* **`lastUpdated`** — compare against your stored timestamp to detect updates without fetching the full response
* **`returnAdminCentreCode`** — tells you which warehouse will process this return
* **`returnOrderNumber`** — the primary key for all subsequent operations

***

{% endstep %}

{% step %}

### Reading `returnItems` — `ReturnOrderItemDto`

Each entry in `returnItems` describes one product being returned and its current processing status.

{% code expandable="true" %}

```json
"returnItems": [
  {
    "id": "653995b0-d9e6-4018-9b85-d66d051b57e7",
    "productCode": "SKU-00123",
    "lineItemId": "1",
    "productDescription": "Classic Leather Wallet",
    "productCustomsDescription": "Full-grain cowhide leather bifold wallet",
    "countryOfOriginIso": "IT",
    "hsCode": "4202.32",
    "productImageUrl": "https://cdn.brand.com/images/sku-00123.jpg",
    "color": "Tan",
    "size": "One Size",
    "category": "ApparelAccessories",
    "personalized": false,
    "dangerousGoods": false,
    "prohibitedForReturns": false,
    "returnItemStatus": "InProgress",
    "rejectionReason": null,
    "returnReasons": [
      {
        "reasonCode": "WrongItemShipped",
        "description": "Wrong item shipped",
        "reasonComment": "Received blue, ordered black",
        "isRetailerAtFault": true,
        "suppliedBy": "Shopper"
      }
    ],
    "weight": {
      "weightTotal": 0.15,
      "weightUnit": "KG"
    },
    "unitPrice": {
      "amount": 89.95,
      "currency": "EUR"
    },
    "shippingInformation": {
      "shippingReference": "REF6993876423",
      "carrierReference": "FBA_1636646500B",
      "barcodeReference": "5 012345 678900",
      "shippingStatus": "Shipped",
      "statusDate": "2024-11-12T14:00:00Z"
    }
  }
]
```

{% endcode %}

<details>

<summary><code>ReturnOrderItemDto</code> field reference</summary>

| Field                       | Description                                                                    |
| --------------------------- | ------------------------------------------------------------------------------ |
| `id`                        | The return item UUID — used when updating item status via `PUT /return-orders` |
| `productCode`               | SKU of the returned product                                                    |
| `lineItemId`                | Original order line item ID                                                    |
| `productDescription`        | Product name                                                                   |
| `productCustomsDescription` | Description for customs documentation                                          |
| `countryOfOriginIso`        | Country of manufacture (ISO 3166-1 alpha-2)                                    |
| `hsCode`                    | Harmonised System classification code                                          |
| `returnItemStatus`          | Current item-level processing status — see Step 5                              |
| `rejectionReason`           | Reason the item was rejected, if applicable                                    |
| `returnReasons`             | Array of return reason objects — see `ReturnItemReasonDto` below               |
| `personalized`              | `true` if the item was customised — affects return eligibility                 |
| `dangerousGoods`            | `true` if classified as hazardous                                              |
| `prohibitedForReturns`      | `true` if the item cannot be returned under the brand's policy                 |
| `shippingInformation`       | Tracking and carrier references — see Step 6                                   |
| `weight`                    | Per-item weight                                                                |
| `unitPrice`                 | Unit price at time of sale                                                     |

</details>

#### `ReturnItemReasonDto`&#x20;

Each `returnReasons` entry captures the return reason:

| Field               | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| `reasonCode`        | The reason code e.g. `"WrongItemShipped"`                   |
| `description`       | Human-readable description of the reason code               |
| `reasonComment`     | Free-text comment from the shopper                          |
| `isRetailerAtFault` | `true` if this return is the retailer's responsibility      |
| `suppliedBy`        | Who provided the reason: `"Shopper"` or `"CustomerService"` |

The `isRetailerAtFault` flag is important for financial settlement — retailer-fault returns may have different refund or cost allocation rules.

***

{% endstep %}

{% step %}

### `ReturnItemStatus`&#x20;

`returnItemStatus` reflects the processing outcome of each individual returned item at the warehouse.

#### `"InProgress"`&#x20;

```json
"returnItemStatus": "InProgress"
```

The return parcel is in transit or has arrived at the warehouse but not yet been inspected and processed. This is the initial status for all items immediately after the return order is created.

**What it means:** The item has not yet been examined — no accept or reject decision has been made.

***

#### `"Accepted"` — item received and accepted

```json
"returnItemStatus": "Accepted"
```

The warehouse has received and inspected the item and determined it is in acceptable condition for restocking or processing.

**What it means:** The item is eligible for a refund. ESW will proceed with the appropriate refund or credit flow.

***

#### `"Rejected"` — item received but rejected

```json
"returnItemStatus": "Rejected",
"rejectionReason": "WrongProduct"
```

The item was received by the warehouse but rejected — either because it does not match what was expected, or because it is not in returnable condition.

**`rejectionReason` examples:** `"WrongProduct"`, `"Damaged"`, `"UsedItem"`, `"MissingTags"`, `"NotOriginalItem"`

**What it means:** The item will not be refunded. Depending on brand policy, the item may be returned to the shopper or disposed of.

***

#### `"RejectedNotReturned"` — rejected and not sent back to shopper

json

```json
"returnItemStatus": "RejectedNotReturned"
```

The item was rejected by the warehouse and will not be returned to the shopper (e.g. disposed of, donated, or recycled per the brand's sustainability policy).

**What it means:** No refund for this item, and the shopper should not expect the item back.

***

#### `"Cancelled"` — item cancelled before processing

```json
"returnItemStatus": "Cancelled"
```

The return of this specific item was cancelled before the warehouse processed it — either by the shopper, a CS agent, or an automated process.

***

#### Item status summary

| Status                | Warehouse received? | Refund eligible? | Item returned to shopper? |
| --------------------- | ------------------- | ---------------- | ------------------------- |
| `InProgress`          | Awaiting            | Unknown          | N/A                       |
| `Accepted`            | ✅ Yes               | ✅ Yes            | No (restocked)            |
| `Rejected`            | ✅ Yes               | ❌ No             | Depends on policy         |
| `RejectedNotReturned` | ✅ Yes               | ❌ No             | ❌ No                      |
| `Cancelled`           | ❌ No                | ❌ No             | N/A                       |

***

{% endstep %}

{% step %}

### `shippingInformation`

`shippingInformation` on each return item provides the carrier and tracking detail for the return shipment.

```json
"shippingInformation": {
  "shippingReference": "REF6993876423",
  "carrierReference": "FBA_1636646500B",
  "barcodeReference": "5 012345 678900",
  "shippingStatus": "Shipped",
  "statusDate": "2024-11-12T14:00:00Z"
}
```

| Field               | Description                                        |
| ------------------- | -------------------------------------------------- |
| `shippingReference` | Your internal shipping reference for this return   |
| `carrierReference`  | The carrier's tracking reference (tracking number) |
| `barcodeReference`  | The barcode on the return label                    |
| `shippingStatus`    | `"Unshipped"`, `"Shipped"`, or `"Cancelled"`       |
| `statusDate`        | When the shipping status was last updated          |

Use `carrierReference` for tracking lookups and for the `POST /tracking-events` request

***

{% endstep %}

{% step %}

### Listing Return Orders (`GET /return-orders`)

The list endpoint retrieves all return orders for a tenant, with optional filters.

```
GET /{identifier}/return-orders
Authorization: Bearer <token>
```

**Query parameters:**

| Parameter    | Type                  | Description                                                   |
| ------------ | --------------------- | ------------------------------------------------------------- |
| `status`     | string                | Filter by `ReturnOrderStatus` — e.g. `"Received"`, `"OnHold"` |
| `returnType` | string                | Filter by `ReturnType` — e.g. `"Normal"`, `"BlindReturn"`     |
| `startUtc`   | ISO 8601 UTC datetime | Filter to returns created on or after this date               |
| `endUtc`     | ISO 8601 UTC datetime | Filter to returns created on or before this date              |

All parameters are optional. Without any filters, all return orders for the tenant are returned.

***

{% endstep %}

{% step %}

### List Query Examples

#### All return orders on hold (requires investigation)

```http
GET /MYBRAND/return-orders?status=OnHold
Authorization: Bearer <token>
```

#### All returns received by the warehouse in the last 7 days

```http
GET /MYBRAND/return-orders?status=Received&startUtc=2024-11-07T00:00:00Z&endUtc=2024-11-14T23:59:59Z
Authorization: Bearer <token>
```

#### All undeliverable returns this month

```http
GET /MYBRAND/return-orders?returnType=Undeliverable&startUtc=2024-11-01T00:00:00Z&endUtc=2024-11-30T23:59:59Z
Authorization: Bearer <token>
```

#### All returns awaiting warehouse processing

```http
GET /MYBRAND/return-orders?status=Created
Authorization: Bearer <token>
```

#### Returns processed (ready for retailer)

```http
GET /MYBRAND/return-orders?status=Processed
Authorization: Bearer <token>
```

***

{% endstep %}

{% step %}

### Interpreting the List Response

The list response (`SearchOrderWebResponse`) returns an array of return order summaries. Each entry has the same top-level fields as the single-order GET response, giving you enough detail to process the list without needing to call the single-order endpoint for each.

{% code expandable="true" %}

```json
[
  {
    "id": "MYBRAND-5000002303",
    "returnOrderNumber": "5000002303",
    "orderReference": "ORD-2024-78542",
    "status": "Received",
    "returnType": "Normal",
    "returnMethod": "Postal",
    "returnAdminCentreCode": "IEDUB",
    "createdOn": "2024-11-10T09:20:51.172Z",
    "lastUpdated": "2024-11-14T11:45:00.000Z",
    "returnItems": [ ... ]
  },
  {
    "id": "MYBRAND-5000002351",
    "returnOrderNumber": "5000002351",
    "orderReference": "ORD-2024-78599",
    "status": "OnHold",
    "returnType": "Normal",
    "returnMethod": "PUDO",
    "returnAdminCentreCode": "IEDUB",
    "createdOn": "2024-11-12T14:33:10.000Z",
    "lastUpdated": "2024-11-13T08:00:00.000Z",
    "returnItems": [ ... ]
  }
]
```

{% endcode %}

***

{% endstep %}

{% step %}

### Polling Patterns and Change Detection

#### Polling for status changes on specific returns

To monitor a specific return order for status changes, poll `GET /return-orders/{returnOrderNumber}` periodically and compare `lastUpdated` against your stored value:

```javascript
async function checkForUpdates(identifier, orderRef, returnOrderNumber, storedLastUpdated) {
  const response = await getReturnOrder(identifier, orderRef, returnOrderNumber);

  if (response.lastUpdated > storedLastUpdated) {
    console.log(`Return ${returnOrderNumber} updated: ${response.status}`);
    await handleStatusChange(response);
    return response.lastUpdated;  // update stored timestamp
  }
  return storedLastUpdated;  // no change
}
```

{% hint style="info" %}
**Recommended polling interval:** 15–60 minutes for active returns. Returns in transit (`Created`) typically update once or twice per day. Returns at the warehouse (`Received`, `OnHold`) may update more frequently during processing hours.
{% endhint %}

#### Batch monitoring with the list endpoint

For operational dashboards, poll the list endpoint with a `status` filter to get all returns in a given state:

```javascript
// Morning operations check — all returns on hold
const onHoldReturns = await listReturnOrders(identifier, { status: 'OnHold' });
const receivedToday = await listReturnOrders(identifier, {
  status: 'Received',
  startUtc: startOfToday(),
  endUtc: endOfToday()
});
```

#### Event-driven alternative

If your integration supports webhooks or event subscriptions, ESW may be able to notify you of status changes rather than requiring polling. Confirm availability with your ESW integration contact.

***

{% endstep %}

{% step %}

### Common Errors

| Status              | Cause                                             | Fix                                                                                  |
| ------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `404` on single GET | `returnOrderNumber` or `orderReference` not found | Verify both path parameters match the values from the `POST /return-orders` response |
| `400` on list GET   | Invalid `status` or `returnType` value            | Use enum values exactly as defined — case-sensitive strings                          |
| `400` on list GET   | `startUtc` after `endUtc`                         | Check date range direction — `startUtc` must be before `endUtc`                      |
| `401`               | Invalid or missing JWT                            | Provide a valid `Authorization: Bearer <token>` header                               |
| `403`               | JWT not scoped to this `{identifier}`             | Confirm the token is issued for the correct tenant                                   |

***

{% endstep %}
{% endstepper %}

### Quick Reference — Key Fields for Integration

| Goal                          | Field to read                                         |
| ----------------------------- | ----------------------------------------------------- |
| Detect any change             | `lastUpdated`                                         |
| Check overall progress        | `status` (ReturnOrderStatus)                          |
| Check per-item outcome        | `returnItems[n].returnItemStatus`                     |
| Find reason item was rejected | `returnItems[n].rejectionReason`                      |
| Get tracking number           | `returnItems[n].shippingInformation.carrierReference` |
| Determine refund eligibility  | `returnItems[n].returnItemStatus == "Accepted"`       |
| Find receiving warehouse      | `returnAdminCentreCode`                               |
| Check if retailer at fault    | `returnItems[n].returnReasons[n].isRetailerAtFault`   |


---

# 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/retrieving-and-listing-return-orders.md?ask=<question>&goal=<endgoal>
```

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