Retrieve returns

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.

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 1000 returns will be displayed in a response. Please use parameters to 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. IMPORTANT: Not all marketplaces supply this data, so this endpoint may not return any information for those specific marketplaces.

examples:

{
    "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

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 API Reference