> 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-2.0/methods/update-an-existing-return-order.md).

# Update An Existing Return Order

To update an existing return order, send a `PUT` request to `/api/v2/Returns`.

Using this request, you can update the return order status (for example, from **Created** to **Processed**) and update return reason codes.

<details>

<summary>Required Parameters</summary>

| **Parameter**       | **Type** | **Description**                                                                                    |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| brandCode           | String   | <p>ESW’s unique identifier for the retailer.</p><p>Example: <code>GOC</code></p>                   |
| brandOrderReference | String   | <p>The retailer's reference number for the order.</p><p>Example: <code>123456789</code></p>        |
| emailAddress        | String   | <p>The email address of the shopper.</p><p>Example: <code><johnsmith@example.com></code></p>       |
| returnOrderNumber   | String   | <p>The return order number generated in the ESW system.</p><p>Example: <code>2123456789</code></p> |
| returnOrderStatus   | Integer  | <p>The status of the return order.</p><p>Example: <code>5</code></p>                               |

</details>

<details>

<summary>Optional Parameters</summary>

| **Parameter**           | **Type** | **Description**                                                                                                                                                                                                                                                                                         |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| returnOrderStatusReason | String   | <p>Reason for the status update.</p><p>Required only when <code>returnOrderStatus</code> is set to <code>OnHold</code>.</p>                                                                                                                                                                             |
| returnOrderArticles     | Array    | <p>Array describing the return order articles.</p><p>Required only when <code>returnOrderStatus</code> is set to <code>Processed</code>.</p><p>Each item typically includes <code>productCode</code>, <code>price</code>, <code>currencyIso</code>, <code>accepted</code>, and <code>reason</code>.</p> |
| requestUpdateLabel      | Boolean  | Indicates if a label should be returned in the response. Values are `true` and `false`.                                                                                                                                                                                                                 |
| requestCreateLabel      | Boolean  | Indicates if a label should be returned in the response. Values are `true` and `false`.                                                                                                                                                                                                                 |

</details>

### Response <a href="#response" id="response"></a>

When you send the API request, the system validates these parameters and searches for the order in the ESW database.

<details>

<summary><strong>HTTP Response Status</strong></summary>

| **Response Code**     | **Description**                                                                                                                                                                                                                                                                                                                                                                              |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **200 - OK**          | <p>Indicates that the validation is successful and the information is updated. The following parameters are returned in the response:</p><ul><li><code>responseMessage</code></li><li><code>brandOrderReference</code></li><li><code>returnOrderNumber</code></li><li><code>updateReturnLabel</code></li><li><code>returnCarrierReference</code></li><li><code>responseCode</code></li></ul> |
| **400 - Bad Request** | Indicates that validation failed due to missing parameters.                                                                                                                                                                                                                                                                                                                                  |
| **404 - Not Found**   | Indicates that the return order could not be found.                                                                                                                                                                                                                                                                                                                                          |

</details>

<details>

<summary>Processing logic by <code>returnOrderStatus</code></summary>

The following table describes how the API request is processed depending on the value of the `returnOrderStatus` request parameter.

| **Parameter:Value**                                                                                              | **Processing**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `returnOrderStatus: OnHold`                                                                                      | <p>The return order is verified to ensure it is not currently on hold.</p><p>If it is on hold, the API response indicates that the return is already on hold.</p><p>If the return order is valid and not on hold, the <code>returnOrder</code> is updated to <code>OnHold</code> for the <code>returnOrderStatusReason</code> supplied.</p>                                                                                                                                                                                                                                                                                                                                                                                    |
| `returnOrderStatus: Released`                                                                                    | <p>The return order is verified to ensure it is currently on hold.</p><p>If the return order is not on hold, the API response indicates that the return order was not on hold.</p><p>If the return order is valid, the return order is updated to <code>Released</code>.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `returnOrderStatus: Processed`                                                                                   | <p>The return order is verified to ensure that the <code>returnOrderArticles</code> match those on the return order. If they do not match, a response is returned indicating that the return order could not be updated as the order articles do not match. If the return order is valid:</p><ul><li>The return order is updated to <code>Processed</code>.</li><li>If the returnOrderArticle reason is <code>ArticleNotIncluded</code> or <code>MissingProduct</code>, this article is removed from the return order, making it available to be returned.</li><li>Each article is updated as <code>Rejected</code> or <code>Accepted</code>.</li><li>For any <code>Accepted</code> article, a refund is calculated.</li></ul> |
| `returnOrderStatus: Cancelled`                                                                                   | <p>The return order is verified to ensure there has been no activity on the order since it was created.</p><p>If there was an activity, for example, if the order status was changed to <code>received</code>, <code>on hold</code>, <code>released</code>, or <code>processed</code>, the return order is not updated and the API returns a corresponding response.</p><p>If there was no activity on the order and the return order is valid, the <code>returnOrder</code> is updated to <code>cancelled</code> and each article in the return order is removed from the return order, making it available to be returned.</p>                                                                                               |
| `"returnOrderStatus" = ["AddedToManifest" OR "SentToRetailer" OR "ReceivedByRetailer" OR "RemovedFromManifest"]` | The `returnOrder` is updated to the returnOrderStatus and additional parameters are returned in the API response.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

</details>

<details>

<summary>If cancellation fails: make an item available for return again</summary>

If a return order could not be cancelled, use the following alternative method to make the return order's item available for return (on a subsequent new return order).

1. Create a `PUT` request for the return order.
2. Set the `returnOrderStatus` to `Processed`.
3. For the `returnOrderArticles` parameter, set accepted to `false` and set `reason` to `ArticleNotIncluded` or `MissingProduct` - as shown in the following code example:

{% code expandable="true" %}

```json
{
  "returnOrderNumber": "2001217608",
  "returnOrderStatus": "Processed",
  "returnOrderStatusReason": "",
  "requestUpdateLabel": false,
  "returnOrderArticles": [
    {
      "productCode": "41115736",
      "price": 10,
      "currencyIso": "USD",
      "accepted": false,
      "reason": "ArticleNotIncluded"
    }
  ],
  "brandCode": "GOC",
  "brandOrderReference": "TH357742535",
  "emailAddress": "test@denmark.com",
  "requestCreateLabel": false
}
```

{% endcode %}

</details>

### Request Example <a href="#request-example" id="request-example"></a>

The following example shows how to update the status of an existing return order.

<details>

<summary>Request body</summary>

{% code expandable="true" %}

```json
{
  "returnOrderNumber": "2312314412",
  "returnOrderStatus": "Processed",
  "returnOrderStatusReason": "",
  "requestUpdateLabel": false,
  "brandCode": "ABC",
  "brandOrderReference": "123456789",
  "emailAddress": "test@example.com",
  "requestCreateLabel": false
}
```

{% endcode %}

</details>

<details>

<summary>Response Example</summary>

{% code expandable="true" %}

```json
{
  "responseMessage": "6",
  "brandOrderReference": "123456789",
  "returnCarrierReference": "AB123456",
  "returnOrderNumber": "2312314412",
  "updateReturnLabel": "",
  "responseCode": "1"
}
```

{% endcode %}

</details>


---

# 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-2.0/methods/update-an-existing-return-order.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.