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

# Update An Existing Return Order

To update an existing return order, for example, to change the status from `Created` to `Processed`, send a `PUT` request to `/api/v2.1/Returns`.

You can also use this request to update return reason codes and label details.

<details>

<summary>Required Parameters</summary>

| **Parameter**           | **Type** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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>0</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| brandCode               | String   | <p>Unique three-letter identifier for the retailer's brand.</p><p>Example: <code>GOC</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| brandOrderReference     | String   | <p>The retailer's unique order reference number for the order.</p><p>Example: <code>1234567890</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| emailAddress            | String   | <p>The email address of the shopper.</p><p>Example: <code><jane@janedoe.com></code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| returnOrderStatusReason | String   | <p>Reasons that explain the return order status.</p><p>Example: <code>Wrong Item Shipped</code></p><p>This parameter is required only if <code>"ReturnOrderStatus": " OnHold"</code>. Otherwise, it is optional.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| returnOrderArticles     | Array    | <p>An array describing the return order articles:</p><ul><li><code>productCode</code>: The product code of the order article. Example, <code>204820</code>.</li><li><code>price</code>: The price of the order article as passed to the checkout. Example, <code>12.34</code>.</li><li><code>currencyIso</code> - The three-letter currency ISO of the order article as passed to the checkout. Example, <code>USD</code>.</li><li><code>accepted</code> - Indicates if the return item is accepted or rejected. If the value is <code>true</code>, <code>reason</code> must be <code>1</code> (Accepted).</li><li><code>reason</code> - The return action applicable to the article.</li></ul><p>This parameter is required only if <code>"ReturnOrderStatus": "Processed"</code>. Otherwise, it is optional.</p><ul><li><code>returnReasonOverride</code> (Integer)- The enumeration associated with the reason for the return that overrides the previously specified reason. Example, <code>9</code> (Length too large). For a complete list, refer to the <a href="https://know.eshopworld.com/page/returns-api">Returns API v2.1 Swagger</a>.</li></ul> |

</details>

<details>

<summary>Optional Parameters</summary>

| **Parameter**      | **Type** | **Description**                                                                           |
| ------------------ | -------- | ----------------------------------------------------------------------------------------- |
| requestUpdateLabel | Boolean  | Indicates if a label should be passed in the response. The values are `true` and `false`. |
| requestCreateLabel | Boolean  | Indicates if a label should be passed in the response. The 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 order 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 your request could not be processed. For example, if the order is cancelled already or the request does not contain the required information.                                                                                                                                                                                                                                       |
| **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 it has not been processed previously. If it has been processed, the API response indicates that the return order could not be updated as the return has already been processed.</p><p>The return order is also 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 returnOrder is valid:</p><ul><li>The return order is updated to <code>Processed</code>.</li><li>If the <code>returnOrderArticle</code> 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 `returnOrderStatus` is updated and the 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": "MAX",
  "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 to Processed.

<details>

<summary>Request body</summary>

{% code expandable="true" %}

```json
{
  "returnOrderNumber": "2123456789",
  "returnOrderStatus": 0,
  "returnOrderStatusReason": "Wrong Item Shipped",
  "requestUpdateLabel": true,
  "returnOrderArticles": [
    {
      "productCode": "1234567890",
      "price": 12.34,
      "currencyIso": "USD",
      "accepted": true,
      "reason": 1
    }
  ],
  "brandCode": "AAA",
  "brandOrderReference": "1234567890",
  "emailAddress": "a@b.com",
  "requestCreateLabel": false
}
```

{% endcode %}

</details>

### Response Example <a href="#response-example" id="response-example"></a>

The following is a sample response based on the example above.

<details>

<summary>Response body</summary>

{% code expandable="true" %}

```json
{
  "responseMessage": 0,
  "brandOrderReference": "1234567890",
  "returnOrderNumber": "2123456789",
  "updateReturnLabel": "VGVzdCBMYWJlbCBQYXlsb2Fk...",
  "returnCarrierReference": "AAB!231",
  "responseCode": 0
}
```

{% 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-v2.1/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.