Returns - e-CROSS Developers Portal

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

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 by ID endpoint.

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 by ID endpoint.

Return awaiting inspection

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

Return finished

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 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 or via the Merchant Admin.

Local fulfillment using returned inventory

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:

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

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

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

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:

{
  "orderId": "ACME-ECOM-TEST-003",
  "fulfillmentWarehouseType": "RETURNS"
}

To retrieve these orders:

use Get order by ID normally, which returns the order regardless of the fulfillment warehouse type
use the fulfillmentWarehouseType filter in 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 endpoint returns only MERCHANT orders by default.

​Overview

​Returns workflow

​Order statuses

​Return reasons

​Returned items classification

​Returns information on the order

​Status history

​RETURN_REQUESTED status

​RETURN_APPROVED status

​RETURN_AWAITING_INSPECTION status

​RETURN_FINISHED status

​RETURN_CANCELLED status

​Item

​Local inventory

​Inventory type

​Tracking orders that generated the inventory position

​Orders fulfilled from returns warehouse

Overview

Returns workflow

Order statuses

Return reasons

Returned items classification

Returns information on the order

Status history

RETURN_REQUESTED status

RETURN_APPROVED status

RETURN_AWAITING_INSPECTION status

RETURN_FINISHED status

RETURN_CANCELLED status

Item

Local inventory

Inventory type

Tracking orders that generated the inventory position

Orders fulfilled from returns warehouse