> 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/create-return-orders.md).

# Create Return Orders

To create a new return order, send a `POST` request to `/api/v2.1/Returns`.

<details>

<summary>Return order types</summary>

You can create a return order as either `Normal`, `Blind`, or `EU Cooling-Off`.

* `Normal`: Shopper creates a return through the Returns portal. This is the default type.
* `Blind`: Shopper returns directly to ESW or the retailer. No portal return is created.
* `EU Cooling-Off`: Return within the EU cooling-off period, protected by EU consumer regulation.

</details>

<details>

<summary>Required Parameters</summary>

| **Parameter**       | **Type** | **Description**                                                                                        |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| brandOrderReference | String   | <p>The retailer's original 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>                |

</details>

<details>

<summary>Optional Parameters</summary>

| **Parameter**          | **Type** | **Description**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| brandReturnOrderNumber | String   | <p>The retailer's reference number for the return order.</p><p>Example: <code>5001006843455</code></p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| returnLineItems        | Array    | <p>An array containing details of the order articles.</p><ul><li><code>brandShippedOrderReference</code> (String) The retailer's shipped order reference that contains the article. Example: <code>6001002976554</code>.</li><li><code>lineItemId</code> (Integer) The line item identifier. Example: <code>20593144</code>.</li></ul><p>Either <code>lineItemId</code> or <code>productCode</code> must be provided.</p><ul><li><code>productCode</code> (String) SKU for the order article. Example: <code>280215</code>.</li><li><code>quantity</code> (Integer) Quantity of the order article. Example: <code>1</code>.</li><li><p><code>unitPrice</code> (JSON) An object containing amount and currency:</p><ul><li><code>amount</code> (Number) Example: <code>87.81</code>.</li><li><code>currency</code> Example: <code>USD</code>.</li></ul></li><li><code>returnReason</code> (Integer) Enumeration for the return reason. Example: <code>9</code> (Length too large). For the full list, refer to the <a href="https://know.eshopworld.com/page/returns-api">Returns API v2.1 Swagger</a>.</li></ul> |
| returnOrderType        | Enum     | The type of the return order. The values are `0`, `1`, and `2`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| requestCreateLabel     | Boolean  | Indicates if a label should be returned in the response. The values are `true` and `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

</details>

ESW uses the following rules when creating returns:

* As a minimum, `brandOrderReference` and `emailAddress` are needed to create a return.
* `returnLineItems` is optional. If supplied, either `lineItemId` or `productCode` must be provided.
* `returnReason` is optional. If provided, it must match ESW return reasons.
* For `EU Cooling-Off` returns, you do not need to specify individual order articles. The request attempts to include all order articles.
* For `Normal` and `Blind` returns, `returnLineItems` must include at least one item with a `productCode` and `returnReason`.

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

When ESW receives the **Create Return** request, it validates it and returns a response. The response indicates whether the data is valid and whether a return is created.

<details>

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

| **Response Code**     | **Description**                                                                                  |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| **200 - OK**          | Indicates that the request is valid and the return order was created.                            |
| **400 - Bad Request** | Indicates that validation failed.                                                                |
| **404 - Not Found**   | Indicates that the system could not create a requested return label (for example, invalid data). |

</details>

<details>

<summary>What happens by return order type</summary>

| **Value**                         | **Actions**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `returnOrderType: "EUCoolingOff"` | <p>The order is verified to ensure it is valid for EU cooling off.</p><p>If the order is not valid, a <strong>400 - Bad Request</strong> message is returned indicating that the return order could not be created. However, if the order is valid:</p><ul><li>A return order is created in the ESW system.</li><li>Each article in the order is marked as <code>Returned</code> with the reason code as <code>CancelRuleInvoked</code> and linked to the return.</li><li>An event called <code>ReturnCancelled</code> is created and assigned to each order article in the database.</li><li>An event called <code>Created</code> is assigned to the return.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                |
| `returnOrderType: "Normal"`       | <p>The order is verified to ensure that matching order articles are available for a return. This verification is done at the <code>lineItemId</code> (if supplied) or <code>productCode</code> level.</p><p>If no order articles are available, a <strong>400 - Bad Request</strong> response is returned indicating that the return order is not created as the order is not valid for a return. However, if the order is valid:</p><ul><li>A return order is created in the ESW system.</li><li>Each article in the order is marked as <code>Returned</code> with the reason code provided in the request and linked to the return.</li><li>An event called <code>ReturnInitiated</code> is created and assigned to each order article in the database.</li><li>An event called <code>Created</code> is assigned to the return.</li></ul>                                                                                                                                                                                                                                            |
| `returnOrderType: "Blind"`        | <p>The order is verified to ensure that matching order articles are available for a return. This verification is done at the <code>lineItemId</code> or <code>productCode</code> level. If no order articles are available, a <strong>400 - Bad Request</strong> response is returned indicating that the return order is not created as the order is not valid for a return. However, if the order is valid:</p><ul><li>A blind return order is created in the ESW system.</li><li>Each article in the order is marked as <code>Returned</code> with the reason code provided in the request and linked to the return.</li><li>An event called <code>ReturnInitiated</code> is created and assigned to each order article in the database.</li><li>An event called <code>Created</code> is assigned to the return.</li></ul><p>All blind returns are processed automatically, which means:</p><ul><li>The status of the <code>returnOrder</code> is updated to <code>Processed</code>.</li><li>Each article is updated as <code>Accepted</code> and a refund is calculated.</li></ul> |

</details>

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

The following example shows how to create a return order without a label. This is typically used when you generate your own return label.

<details>

<summary>Request body</summary>

{% code expandable="true" %}

```json
{
  "brandOrderReference": "TH446395780",
  "brandReturnOrderNumber": "5001006843455",
  "emailAddress": "test@gmail.com",
  "returnLineItems": [
    {
      "brandShippedOrderReference": "6001002976554",
      "lineItemId": 20593144,
      "productCode": "280215",
      "unitPrice": {
        "amount": 87.81,
        "currency": "USD"
      },
      "quantity": 2,
      "returnReason": 1
    }
  ],
  "returnOrderType": 0,
  "requestCreateLabel": false
}
```

{% endcode %}

</details>

<details>

<summary>Response Example</summary>

{% code expandable="true" %}

```json
{
  "brandOrderReference": "123456789",
  "returnOrderNumber": "2123456789",
  "createReturnLabel": "",
  "returnCarrierReference": "ABC123"
}
```

{% endcode %}

</details>

### Generate a return label <a href="#generate-a-return-label" id="generate-a-return-label"></a>

To generate a return label while creating the return order, set `requestCreateLabel` to `true` in the request body.

When the return is ready to be created in the database, the system checks the value of `requestCreateLabel`. If the value is `true`, the system attempts to generate a label (shopper-paid or prepaid). If it fails to generate the label (for example, due to invalid shopper address data), an HTTP `404` response is returned.

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

<details>

<summary>Request body</summary>

{% code expandable="true" %}

```json
{
  "brandOrderReference": "TH446395780",
  "brandReturnOrderNumber": "5001006843455",
  "emailAddress": "test@gmail.com",
  "returnLineItems": [
    {
      "brandShippedOrderReference": "6001002976554",
      "lineItemId": 20593144,
      "productCode": "280215",
      "unitPrice": {
        "amount": 87.81,
        "currency": "USD"
      },
      "quantity": 2,
      "returnReason": 1
    }
  ],
  "returnOrderType": 0,
  "requestCreateLabel": true
}
```

{% endcode %}

</details>

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

<details>

<summary>Response body</summary>

{% code expandable="true" %}

```json
{
  "brandOrderReference": "123456789",
  "returnOrderNumber": "2123456789",
  "createReturnLabel": "VGVzdCBMYWJlbCBQYXlsb2Fk....",
  "returnCarrierReference": "ABC123"
}
```

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