Skip to main content

​
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

1

Customer requests a return

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 API.
2

Reverse logistics

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 API.
3

Return received

The products are received in the local warehouse, inspected and stored.At this moment the order status changes to RETURNED and the related information gets available in the order status history, that can be retrieved using the Get Order API.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 incresed in the local warehouse. All the inventory information can be queried using the List Inventory API or via the Merchant Admin.

​
Order statuses

The following order statuses are related to returns.
StatusDescription
RETURN_REQUESTEDCustomer requested to return one or more items from the received order.
RETURN_APPROVEDOrder return process has been approved (label generated, pickup scheduled, drop-off address defined,..)
RETURN_FINISHEDOrder has been returned and the items are available in the local warehouse.
RETURN_CANCELLEDReturn process was cancelled.

​
Return reasons

The following return reasons are available:
CodeDescription
SIZE_NOT_FITThe item does not fit the customer’s size.
DISLIKEThe customer does not like the item.
REGRETThe customer regretted the purchase.
DAMAGEDThe item is damaged or defective.
OTHEROther reason not mapped. The details are optionally provided in the reasonDetails field.

​
Returned items classification

The following returned items classification are available:
CodeDescription
NEWThe item is in a good condition.
NEW_NO_BOXThe item is in a good condition but doesn’t come with the original box.
NEW_DAMAGED_BOXThe item is in a good condition but the original box is damaged.
DAMAGEDThe 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: 
{
  "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: 
{
  "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_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: 
{
  "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: 
{
  "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: 
{
  "id": "gid://shopify/LineItem/111111111111",
  "salesChannelSkuId": "111111111111",
  "quantity": 1,
  // ...
  "returns": [
    {
      "returnRequestedDate": "2025-12-08T12:05:20Z",
      "returnApprovedDate": "2025-12-08T12:05:20Z",
      "returnedDate": "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 is RETURNED, the items are available in the local warehouse, 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 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: 
{
  "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
    }
  ]
}