> ## Documentation Index > Fetch the complete documentation index at: https://developers.e-cross.tech/llms.txt > Use this file to discover all available pages before exploring further. # Returns > Complete guide to managing returns with e-CROSS ## Overview After an order is delivered the buyer has the right to return one or more items from the order, according to local laws and regulations. This guide walks you through the complete returns workflow. ## Returns workflow The customer requests a return for one or more items via the sales channel and the request reaches to e-CROSS. At this moment the order status changes to `RETURN_REQUESTED` and the requested items and, optionally, the request reason, are available in the order status history, that can be retrieved using the [Get order by ID](/api-reference/orders/get-order-by-id) endpoint. The reverse logistics process is approved, according to the specific processes of each country. This includes the generation of the return label, the pickup schedule, the drop-off address, etc. The reverse logistics information is shared with the customer via the sales channel, via the brand's or the marketplace's customer service. At this moment the order status changes to `RETURN_APPROVED` and the related information gets available in the order status history, that can be retrieved using the [Get order by ID](/api-reference/orders/get-order-by-id) endpoint. Reverse logistics delivers the return to the returns warehouse or fulfillment center. The items are received but inspection is still pending. At this moment the order status changes to `RETURN_AWAITING_INSPECTION` and the related information becomes available in the order status history, which you can retrieve using the [Get order by ID](/api-reference/orders/get-order-by-id) endpoint. This is an optional step and it may or may not exist in the return process, depending on the operational processes of each country / partner. The products are inspected and classified in the returns warehouse. At this moment the order status changes to `RETURN_FINISHED` and the related information becomes available in the order status history, which you can retrieve using the [Get order by ID](/api-reference/orders/get-order-by-id) endpoint. The items that are in a good condition to be sold as new have their `Available` position increased in the local warehouse. Items that are not in a good condition have their `Damaged` inventory position increased in the local warehouse. All the inventory information can be queried using the [List Inventory API](/api-reference/merchant-catalog/list-inventory) or via the Merchant Admin. The e-CROSS platform automatically decides whether a new order will follow the local fulfillment flow or the regular international flow. When all the items of the order have local stock available in the returns warehouse, the order is fulfilled by that warehouse instead of the international flow. If one item has both local and international availability but another item has only international availability, the whole order is treated as an international order. In this case the local stock remains available and is not allocated to that order. When the order is fulfilled locally, it contains `fulfillmentWarehouseType = RETURNS`. The commercial invoice and the dispatch label are generated normally, and the full order lifecycle and statuses are generated in the same way as any other order, allowing the sales channel and integrators to track it normally. The operational fulfillment is handled end-to-end by the returns partner until the delivery to the customer. ## Order statuses The following order statuses are related to returns. | Status | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------- | | RETURN\_REQUESTED | Customer requested to return one or more items from the received order. | | RETURN\_APPROVED | Order return process has been approved (label generated, pickup scheduled, drop-off address defined,..) | | RETURN\_AWAITING\_INSPECTION | Return shipment reached the returns warehouse or fulfillment center and items are pending inspection. | | RETURN\_FINISHED | Order has been returned, items were inspected, and inventory (available or damaged) are updated. | | RETURN\_CANCELLED | Return process was cancelled. | ## Return reasons The following return reasons are available: | Code | Description | | -------------- | ------------------------------------------------------------------------------------------ | | SIZE\_NOT\_FIT | The item does not fit the customer's size. | | DISLIKE | The customer does not like the item. | | REGRET | The customer regretted the purchase. | | DAMAGED | The item is damaged or defective. | | OTHER | Other reason not mapped. The details are optionally provided in the `reasonDetails` field. | ## Returned items classification The following returned items classification are available: | Code | Description | | ----------------- | ----------------------------------------------------------------------- | | NEW | The item is in a good condition. | | NEW\_NO\_BOX | The item is in a good condition but doesn't come with the original box. | | NEW\_DAMAGED\_BOX | The item is in a good condition but the original box is damaged. | | DAMAGED | The item is damaged and can't be sold as new. | ## Returns information on the order The returns information is available in the order in the following fields. ### Status history #### RETURN\_REQUESTED status For the `RETURN_REQUESTED` status, the status history entry contains the following information: * local warehouse that will handle the return * which items are being returned * the reason for the return * the user that performed the operation Status history entry example: ```json theme={null} { "status": "RETURN_REQUESTED", "eventDate": "2025-12-08T12:05:20Z", "receivedDate": "2025-12-08T12:05:20Z", "username": "john.doe@e-cross.tech", "eventData": { "returnsWarehouse": { "id": 100, "name": "Returns partner BR", }, "items": [ { "id": "gid://shopify/LineItem/111111111111", "salesChannelSkuId": "111111111111", "quantity": 1, "reasonCode": "SIZE_NOT_FIT", "reasonDetails": "Size not fit", }, { "id": "gid://shopify/LineItem/333333333333", "salesChannelSkuId": "333333333333", "quantity": 1, "reasonCode": "OTHER", "reasonDetails": "Customer didn't specify a reason", } ] } } ``` #### RETURN\_APPROVED status For the `RETURN_APPROVED` status, the status history entry contains the following information: * reverse logistics information * the user that performed the operation Status history entry example: ```json theme={null} { "status": "RETURN_APPROVED" "eventDate": "2025-12-09T12:05:20Z", "receivedDate": "2025-12-09T12:05:20Z", "username": "john.doe@e-cross.tech", "eventData": { "postageCode": "1927831873", "label": "https://......", "dropOffAddress": "123 Main St, Anytown, USA" }, } ``` #### RETURN\_AWAITING\_INSPECTION status For the `RETURN_AWAITING_INSPECTION` status, the status history entry contains the following information: * the return identifier * the user that performed the operation, when available Status history entry example: ```json theme={null} { "status": "RETURN_AWAITING_INSPECTION", "eventDate": "2025-12-10T12:05:20Z", "receivedDate": "2025-12-10T12:05:20Z", "username": "john.doe@e-cross.tech", "eventData": { "returnId": "5b24e009-c257-4ddb-9a6e-6e98fd371bce" } } ``` This entry can be created automatically by logistics tracking integrations or set manually by operations. #### RETURN\_FINISHED status For the `RETURN_FINISHED` status, the status history entry contains the following information: * which items were returned and their quantity * the inbound details of the items (images, classification, etc.) * the user that performed the operation Status history entry example: ```json theme={null} { "status": "RETURN_FINISHED", "eventDate": "2025-12-11T12:05:20Z", "receivedDate": "2025-12-11T12:05:20Z", "username": "john.doe@e-cross.tech", "eventData": { "items": [ { "id": "gid://shopify/LineItem/111111111111", "salesChannelSkuId": "111111111111", "quantity": 1, "images": ["https://........"], "classification": "NEW" }, { "id": "gid://shopify/LineItem/333333333333", "salesChannelSkuId": "333333333333", "quantity": 1, "images": ["https://........"], "classification": "DAMAGED" } ] } } ``` #### RETURN\_CANCELLED status For the `RETURN_CANCELLED` status, the status history entry contains the dates and the user that performed the operation Status history entry example: ```json theme={null} { "status": "RETURN_CANCELLED", "eventDate": "2025-12-11T12:05:20Z", "receivedDate": "2025-12-11T12:05:20Z" "username": "jonh.doe@e-cross.tech" } ``` ### Item The order item involved in the return contains an additional attribute named `returns`, which is a list of returns related to the item. All the returns information related to the item is store in this attribute. This is pretty much a subset of the order `statusHistory` information, specific related to the item. Example: ```json theme={null} { "id": "gid://shopify/LineItem/111111111111", "salesChannelSkuId": "111111111111", "quantity": 1, // ... "returns": [ { "returnRequestedDate": "2025-12-08T12:05:20Z", "returnApprovedDate": "2025-12-09T12:05:20Z", "returnAwaitingInspectionDate": "2025-12-10T12:05:20Z", "returnFinishedDate": "2025-12-11T12:05:20Z", "returnsWarehouseId": 100, "returnsWarehouseName": "Returns partner BR", "quantity": 1, "reasonCode": "SIZE_NOT_FIT", "reasonDetails": "Size not fit", "quantityReturned": 1, "images": ["https://........"], "classification": "NEW", "label": "https://......" } ] } ``` ## Local inventory ### Inventory type Once the order reaches the status `RETURN_FINISHED`, the items are available in the local warehouse stock positions, according to the classification of the items: * if the item is in a good condition, then the inventory will have the `AVAILABLE` type * if the item is damaged, then the inventory will have the `DAMAGED` type The local inventory information can be queried using the [List Inventory API](/api-reference/merchant-catalog/list-inventory) or via the Merchant Admin. ### Tracking orders that generated the inventory position To track which returned orders generated the inventory position you can inspect the `inventory.returnedOrders` field. Example: ```json theme={null} { "id": "ACME-1234567891-1", "skuId": "1234567891", "skuName": "T-Shirt", "merchantId": "ACME", "quantity": 1, "inventoryType": "AVAILABLE", "lastUpdateDate": "2024-01-17T19:58:53.270Z", "warehouseId": 1000, "warehouseName": "Returns partner BR", "warehouseCountry": "BR", "returnedOrders": [ { "orderId": "ACME-ECOM-TEST-003", "returnedDate": "2024-01-17T19:58:53.270Z", "quantity": 1 } ] } ``` ## Orders fulfilled from returns warehouse When a new order is fulfilled using local inventory from the returns warehouse, the order JSON contains the `fulfillmentWarehouseType` field. Possible values: * `MERCHANT`: the regular international order flow * `RETURNS`: the order is fulfilled locally by the returns partner Example: ```json theme={null} { "orderId": "ACME-ECOM-TEST-003", "fulfillmentWarehouseType": "RETURNS" } ``` To retrieve these orders: * use [Get order by ID](/api-reference/orders/get-order-by-id) normally, which returns the order regardless of the fulfillment warehouse type * use the `fulfillmentWarehouseType` filter in [List orders](/api-reference/orders/list-orders) The `fulfillmentWarehouseType` filter accepts: * `MERCHANT` to retrieve the current international orders * `RETURNS` to retrieve orders fulfilled locally by the returns partner * `MERCHANT,RETURNS` to retrieve both types in the same request If the filter is omitted, the [List orders](/api-reference/orders/list-orders) endpoint returns only `MERCHANT` orders by default.