> 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/create-a-return-order.md). # Create A Return Order To create a new return order, send a `POST` request to `/api/v2/Returns`. You can create a return order for the entire order or specific line items/order articles within the order. The `cancelOrder` parameter in the API request allows you to specify this. Optionally, you can also generate a return label by setting the `requestCreateLabel` parameter to `true`.
Required Parameters | **Parameter** | **Type** | **Description** | | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cancelOrder | Boolean |

Indicates if the EU Consumer Return Guarantee should be implemented for the order. Values are true or false.

If all conditions are met, a return order containing all order articles is created.

| | orderArticles | Array |

An array containing order article details.

Required only when cancelOrder is false.

| | brandCode | String |

ESW’s unique identifier for the retailer.

Example: GOC

| | brandOrderReference | String |

The retailer's reference number for the order.

Example: 123456789

| | emailAddress | String |

The email address of the shopper.

Example:

|
Optional Parameters | **Parameter** | **Type** | **Description** | | ------------------ | -------- | --------------------------------------------------------------------------------------- | | requestCreateLabel | Boolean | Indicates if a label should be returned in the response. Values are `true` and `false`. |
### Response When you send the API request, the system validates it and attempts to create a return order in the ESW database.
HTTP Response Status | **Response Code** | **Description** | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | **400 - Bad Request** | Indicates that the order could not be created. | | **201 - Created** | Indicates that the return order is created. The API response varies depending on whether the `cancelOrder` parameter is `true` or `false`. | | **404 - Not Found** | Indicates that a requested return label could not be created (for example, invalid shopper address). |
What happens by cancelOrder value **cancelOrder: `true`** If `cancelOrder` is `true`, the order is verified to ensure it is valid for cancellation. If the order is not valid for cancellation, the API returns **400 - Bad Request** indicating that order cancellation is not allowed. If the order is valid for cancellation, the following events take place: * A return order is created in the ESW database. * Each order article is marked as Cancelled or Returned with the reason code as `CancelRuleInvoked` and linked to the return. * An event is created and assigned to the order article in the database. * The status of the return is updated to **Created**. In the request body, either: * `cancelOrder` must be `true`, or * `orderArticles` must contain at least one article with `productCode`, `currencyIso`, `returnReason`, and `price` greater than 0. **cancelOrder: `false`** If `cancelOrder` is `false`, the order is verified to ensure that the matching order articles are available for a return. This verification is done at the `productCode` level. If no order articles are available, the API returns **400 - Bad Request** indicating that the return order is not created as the order is not valid for a return. If matching order articles are available: * A return order is created in the ESW database. * Each order article in the request is marked as Returned with a reason code and linked to the return. * An event is created and assigned to the order article in the database. * The status of the return is updated to **Created**.
### Request Example The following example shows how to create a return order without a label. This is typically used when you generate your own return label.
Request body {% code expandable="true" %} ```json { "cancelOrder": false, "orderArticles": [ { "productCode": "123456", "price": 12.34, "currencyIso": "EUR", "returnReason": "WrongItemShipped" } ], "brandCode": "ABC", "brandOrderReference": "123456789", "emailAddress": "test@example.com", "requestCreateLabel": false } ``` {% endcode %}
Response Example {% code expandable="true" %} ```json { "responseMessage": "5", "brandOrderReference": "123456789", "returnOrderNumber": "2123456789", "createReturnLabel": "", "responseCode": "1" } ``` {% endcode %}
### Generate a return label To generate a return label while creating the return order, set the `requestCreateLabel` parameter to `true` in the `POST` request. When the return is ready to be created in the database, the system checks the value of the `requestCreateLabel` parameter in the API. If the value is `true`, the system attempts to generate a label, which can be either shopper-paid or prepaid. If the system fails to generate a label due to any reason, for example, an invalid shopper address, an HTTP 404 response is returned indicating that the label could not be created. #### Request Example The following example shows how to create a return for an existing order and request a return label.
Request body {% code expandable="true" %} ```json { "cancelOrder": false, "orderArticles": [ { "productCode": "123456", "price": 12.34, "currencyIso": "EUR", "returnReason": "WrongItemShipped" } ], "brandCode": "ABC", "brandOrderReference": "123456789", "emailAddress": "test@example.com", "requestCreateLabel": true } ``` {% endcode %}
#### Response Example
Response body {% code expandable="true" %} ```json { "responseMessage": "5", "brandOrderReference": "123456789", "returnOrderNumber": "2123456789", "createReturnLabel": "VGhpcyBpcyBhIHRlc3QgbGFiZWwgd2l0aCBub3RoaW5nIGluIGl0IGFzIGl0IGlzIGp1c3QgZm9yIGFuIGV4YW1wbGU=", "responseCode": "1" } ``` {% 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-2.0/methods/create-a-return-order.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.