Customer Return Shipments

Customer return shipments (RMAs) are inbound flows from the end customer back to the 3PL. The integration polls for them, acknowledges receipt, and reports per-line received and damaged quantities with optional return reasons.

List customer return shipments 🔗

Text

1
GET /v1/customer-return-shipments.json

Query parameters

Name	Type	Description
`status`	string	`pending` (default), `open`, `done`, `canceled`
`page`	integer	1-indexed page number (100 records per page)
`ids`	string	Comma-separated internal ids
`numbers`	string	Comma-separated return shipment numbers
`planned_date_min`	date	Lower bound on `planned_date`
`planned_date_max`	date	Upper bound on `planned_date`
`updated_at_min`	datetime	Lower bound on last modification time
`updated_at_max`	datetime	Upper bound on last modification time

Status meanings

pending — draft return, not yet acknowledged by the 3PL
open — acknowledged, awaiting items
done — items received (state is received or done)
canceled — cancelled before receipt

Response

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
{
  "data": [
    {
      "id": 300789,
      "number": "CR-300789",
      "company_code": "ACME",
      "warehouse": { "id": 3, "code": "LAX", "name": "Los Angeles" },
      "planned_date": "2026-06-24",
      "customer": {
        "name": "Jane Doe",
        "email": "jane@example.com",
        "code": "CUST-42"
      },
      "origin_address": {
        "address1": "123 Main St",
        "city": "Los Angeles",
        "zip": "90012",
        "country_code": "US",
        "subdivision_code": "CA"
      },
      "delivery_address": {
        "address1": "500 Warehouse Way",
        "city": "Los Angeles",
        "zip": "90021",
        "country_code": "US",
        "subdivision_code": "CA"
      },
      "carrier_code": "ups",
      "service_code": "ground",
      "tracking_number": {
        "tracking_number": "1Z999AA10123456784",
        "carrier_identifier": "ups",
        "state": "in_transit"
      },
      "lines": [
        {
          "id": 8001,
          "product": { "code": "SKU-100", "name": "Widget" },
          "quantity": 1,
          "unit": "u",
          "return_reason": {
            "id": 42,
            "name": "Wrong size",
            "return_type": "refund"
          },
          "order": {
            "id": 900,
            "number": "SO-900",
            "reference": "shopify-1234"
          },
          "unit_price": 25.00,
          "currency": "USD"
        }
      ],
      "request_confirmation": false
    }
  ],
  "has_more": false
}

Acknowledge return shipments 🔗

Text

1
PUT /v1/customer-return-shipments/acknowledge.json

Signals that the 3PL is expecting the return. Shipment must be in the draft state and not already acknowledged.

Request body

JSON

1
2
3
{
  "shipments": [{ "id": 300789 }]
}

Response

JSON

1
2
3
4
5
{
  "shipments": [
    { "id": 300789, "acknowledged_at": "2026-06-17T18:33:00+00:00", "errors": null }
  ]
}

Returns 200 if every item succeeded, 207 if some failed.

Receive return shipments 🔗

Text

1
PUT /v1/customer-return-shipments/receive.json

Mark return shipments as received and post per-line received and damaged quantities.

Request body

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "shipments": [
    {
      "id": 300789,
      "receiving_strategy": "split_and_keep_open",
      "items": [
        {
          "sku": "SKU-100",
          "received_quantity": 1,
          "return_reason": 42
        }
      ]
    }
  ]
}

Item fields

Field	Type	Notes
`sku`	string	Required
`received_quantity`	number	At least one of `received_quantity` or `damaged_quantity` is required. Legacy `quantity` accepted as alias.
`damaged_quantity`	number	See above
`lot_number`	string	Required for lot-tracked SKUs
`return_reason`	integer	Return reason id (see Fulfil settings)

receiving_strategy values

split_and_keep_open (default) — split off the received items; keep the return open for further items
finalize_and_start_new — close the original return; open a new one for any remaining items

Response

JSON

1
2
3
4
5
{
  "shipments": [
    { "id": 300789, "errors": null }
  ]
}

Returns 200 / 207 with per-item errors.