---
title: Retrieve returns
slug: merchant-api/retrieve-returns
createdAt: 2021-07-13T13:47:11.000Z
---

# Definition

Certain marketplaces provide information about incoming returns through their APIs. Neteven can then make this information accessible via the endpoint below, allowing you to visualize and anticipate which items customers are returning to your warehouses. 

:::hint{type="info"}
Please note that this endpoint is for informational purposes only. You must still utilize the PATCH order/line/refund method to process a return and issue a refund to the customer once the physical parcel arrives at your warehouse.
:::



# Endpoints

## Get orders returns

### Endpoint definition

| `GET`              | `/merchant/orders/returns`                                                                                                                                                                                          |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Description**    | displays order returns and their items.                                                                                                                                                                             |
| **Required scope** | `order_reader`                                                                                                                                                                                                      |
| **Pagination**     | Please note that by default a maximum of<br />1000 returns will be displayed in a response. Please use parameters to<br />get results customized to your requirements.                                              |
| **Filtering**      | Several different filtering options exist (marketplace\_ids, return\_status, date brackets, etc). Use a combination to restrict the results to what is relevant for you.                                            |
| **Returns**        | array of `return` objects, corresponding to the input parameters.<br /><br />**IMPORTANT**: Not all marketplaces supply this data, so this endpoint may not return any information for those specific marketplaces. |

**examples:**

:::CodeblockTabs
request

```curl
curl --request GET \
  --url 'https://api.neteven.com/v1/merchant/orders/returns?limit=10&marketplace_ids=115' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer $MYTOKEN' \
  --header 'Content-Type: application/json'
```

200 OK response

```javascript
{
    "data": {
        "returns": [
            {
                "marketplace_id": 115,
                "marketplace_name": "farfetch_fr",
                "marketplace_return_id": "101",
                "order_id": 3000006,
                "marketplace_order_id": "177110001",
                "return_status": "SHIPPED",
                "date_created": "2024-11-10T09:02:50",
                "date_updated": "2024-11-10T09:02:50",
                "stock_location": {
                    "stock_location_id": 101,
                    "name": "Farfetch StockPoint 001",
                    "properties": {
                        "COUNTRY_ID": "FR",
                        "CURRENCY_ID": "EUR",
                        "STORE_ID": "123"
                    }
                },
                "return_lines": [
                    {
                        "order_line_id": 4470001,
                        "marketplace_order_line_id": "900000001",
                        "returned_quantity": 1,
                        "additional_information": {
                            "reason": "Item is too big"
                        },
                        "item": {
                            "sku": "mySKU-456",
                            "ean": "10987654321",
                            "marketplace_product_identifier": "10987654321"
                        }
                    }
                ]
            },
            {
                "marketplace_id": 115,
                "marketplace_name": "farfetch_fr",
                "marketplace_return_id": "102",
                "order_id": 3000007,
                "marketplace_order_id": "177110002",
                "return_status": "SHIPPED",
                "date_created": "2024-11-10T09:02:45",
                "date_updated": "2024-11-10T09:02:45",
                "stock_location": {
                    "stock_location_id": 101,
                    "name": "Farfetch StockPoint 001",
                    "properties": {
                        "COUNTRY_ID": "FR",
                        "CURRENCY_ID": "EUR",
                        "STORE_ID": "123"
                    }
                },
                "return_lines": [
                    {
                        "order_line_id": 4470002,
                        "marketplace_order_line_id": "900000002",
                        "returned_quantity": 1,
                        "additional_information": {
                            "reason": "Changed my mind"
                        },
                        "item": {
                            "sku": "mySKU-123",
                            "ean": "12345678910",
                            "marketplace_product_identifier": "12345678910"
                        }
                    }
                ]
            },
        ]
    },
    "metadata": {
        "number_of_results": 2,
        "api_version": 1,
        "api_version_expiration_date": "2027-12-31",
        "total_count": 722,
        "limit": 2,
        "offset": 0
    }
}
```
:::

### Endpoint specific errors

:::hint{type="success"}
This endpoint should never return any error besides validation errors (misuse of query params). If no returns are available, the `data.returns` list in the response will simply be empty.
:::

***

# API reference

*more information on parameters, responses and content in the&#x20;*[API Reference](docId\:yWeBKEf7Kqp3agiK6LtoJ)&#x20;