Return

Endpoints

Method	Endpoint	Description
GET	/api/v202608/return-uploads	Get return-upload list
POST	/api/v202608/return-uploads	Create return-uploads (batch submit)
PUT	/api/v202608/return-uploads/{upload_id}	Update a return-upload (only `Pending` status is editable)
DELETE	/api/v202608/return-uploads/{upload_id}	Cancel a return-upload
GET	/api/v202608/returns	Get return order list (own company)
GET	/api/v202608/returns	Get unclaimed return list (`index.by-unclaimed`)

[NEW] v202608 New Endpoints (2026-09 Patch): All 6 Return endpoints below are new in this release; v202206 does not provide them.
Concept distinction:
Return upload (return-upload): A client declaration via API stating "these tracking numbers are coming back".
Return order (return): Auto-created by the warehouse when the package is scanned at receiving. Read-only to the client.
When the warehouse scans the tracking number, the matching upload transitions to Matched and a return order is auto-created.

Header

Key	Value
Authorization	Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...

GET /api/v202608/return-uploads (Get return-upload list)

Request

Params

Type	Name	Description	Required/Optional	Schema
query	api	API type Available Values: index.by-default	required	enum
query	upload_id	Upload id	optional	integer
query	tracking_number	Tracking number (fuzzy match)	optional	string
query	return_from	Source filter: 1: Buyer, 2: FBA, 3: Third-Party	optional	integer
query	reference_id	Client-defined reference number used to link back to the client's internal document. When creating an upload, you may pass any string (no uniqueness check) such as the original outbound order number, RMA number, or client order number. This field filters by exact value.	optional	string
query	upload_status	Upload status Available Values: Pending: Waiting for the warehouse to scan and match Matched: The warehouse has scanned the corresponding package and created a return order Cancelled: Cancelled by the client Expired: Not matched within 90 days; expired automatically by the system	optional	enum
query	matched	Whether already matched to a Return order (`true` = only return Matched; `false` = exclude Matched)	optional	boolean
query	created_at_from	Created time from Timezone: Pacific Standard Time	optional	datetime
query	created_at_to	Created time to Timezone: Pacific Standard Time	optional	datetime
query	updated_at_from	Updated time from Timezone: Pacific Standard Time	optional	datetime
query	updated_at_to	Updated time to Timezone: Pacific Standard Time	optional	datetime
query	next_token	Token for the next page	optional	string

Request Example

GET /api/v202608/return-uploads?api=index.by-default&upload_status=Pending&created_at_from=2026-08-01%2000:00:00&created_at_to=2026-08-31%2023:59:59

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
upload_id	Upload id	integer
tracking_number	Tracking number	string
return_from	Source id	integer
return_from_name	Source display name (`Buyer` / `FBA` / `Third Party`)	string
reference_id	Client-defined reference number (e.g. original outbound order number, RMA number, order number)	string
return_action	Disposition action Available Values: Putaway: put back to stock, Disposal: destroy	string
upload_status	Upload status: Pending: Waiting for the warehouse to scan and match Matched: The warehouse has scanned the corresponding package and created a return order Cancelled: Cancelled by the client Expired: Not matched within 90 days; expired automatically by the system	string
matched_return_id	Return order id linked after matching (null if not matched)	integer
matched_at	Match time (equals the Return order created time) Timezone: Pacific Standard Time	datetime
expected_items	Expected line items array	array
expires_at	Expiration time (default 90 days after creation) Timezone: Pacific Standard Time	datetime
created_at	Created time Timezone: Pacific Standard Time	datetime
updated_at	Updated time Timezone: Pacific Standard Time	datetime

expected_items sub-structure

Name	Description	Schema
customer_sku	Client SKU code	string
fnsku	Amazon FNSKU	string
lpn	LPN	string
qty	Expected quantity	integer
notes	Notes	string

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "upload_id": 5678,
                "tracking_number": "9400111899223345678901",
                "return_from": 1,
                "return_from_name": "Buyer",
                "reference_id": "RA20260807001",
                "return_action": "Putaway",
                "upload_status": "Pending",
                "matched_return_id": null,
                "matched_at": null,
                "expected_items": [
                    { "customer_sku": "CUS-SKU-001", "fnsku": null, "lpn": null, "qty": 1, "notes": null }
                ],
                "expires_at": "2026-11-05 02:00:00",
                "created_at": "2026-08-07 02:00:00",
                "updated_at": "2026-08-07 02:00:00"
            }
        ],
        "next_token": null
    }
}

POST /api/v202608/return-uploads (Create return-uploads)

Batch submit, all-or-nothing: if any tracking number fails validation, the entire batch is rejected.

Request

Params

Type	Name	Description	Required/Optional	Schema
query	api	API type Available Values: store.by-default	required	enum
body	return_uploads	Array of uploads	required	array

return_uploads sub-structure

Name	Description	Required/Optional	Schema
tracking_number	Tracking number (must not be empty; must not repeat within the same batch)	required	string
return_from	Source Available Values: 1: Buyer, 2: FBA, 3: Third-Party	optional	enum
reference_id	Reference number	optional	string
return_action	Disposition action Available Values: Putaway (default), Disposal	optional	enum
expected_items	Expected line items array (may be empty)	optional	array

expected_items sub-structure (all fields optional)

Name	Description	Required/Optional	Schema
customer_sku	Client SKU code	optional	string
fnsku	Amazon FNSKU	optional	string
lpn	LPN	optional	string
qty	Expected quantity	optional	integer
notes	Notes	optional	string

Request Example

{
    "return_uploads": [
        {
            "tracking_number": "9400111899223345678901",
            "return_from": 1,
            "reference_id": "RA20260807001",
            "return_action": "Putaway",
            "expected_items": [
                { "customer_sku": "CUS-SKU-001", "fnsku": null, "lpn": null, "qty": 1, "notes": "Buyer changed mind and returned" }
            ]
        },
        {
            "tracking_number": "9400111899223345678902",
            "return_from": 2,
            "reference_id": "RMA-FBA-20260807-A",
            "return_action": "Disposal"
        }
    ]
}

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
return_uploads	Array of created uploads; each item contains `upload_id` + `tracking_number` (for reverse-mapping lookup)	array

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "return_uploads": [
            { "upload_id": 5678, "tracking_number": "9400111899223345678901" },
            { "upload_id": 5679, "tracking_number": "9400111899223345678902" }
        ]
    }
}

PUT /api/v202608/return-uploads/{upload_id} (Update a return-upload)

Only Pending status is editable (cannot be modified once Matched). tracking_number is the matching key and cannot be modified.

Partial update semantics: only fields explicitly sent by the client are written; fields not sent keep their original values. When expected_items is sent, it fully replaces the previous array (not an incremental merge).

Request

Params

Type	Name	Description	Required/Optional	Schema
path	upload_id	Target upload id	required	integer
query	api	API type Available Values: update.by-default	required	enum
body	return_from	Source	optional	integer
body	reference_id	Reference number	optional	string
body	return_action	Disposition action (`Putaway` / `Disposal`)	optional	enum
body	expected_items	Line items array (fully replaces the previous array)	optional	array

Note: To change the tracking number, cancel the old upload first and then create a new one.

Request Example

PUT /api/v202608/return-uploads/5678?api=update.by-default

{
    "reference_id": "RA20260807001-REV",
    "return_action": "Disposal",
    "expected_items": [
        { "customer_sku": "CUS-SKU-001", "qty": 2, "notes": "Client changed quantity" }
    ]
}

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
upload_id	Upload id	integer
tracking_number	Tracking number	string

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "upload_id": 5678,
        "tracking_number": "9400111899223345678901"
    }
}

DELETE /api/v202608/return-uploads/{upload_id} (Cancel a return-upload)

Only Pending status is cancellable. After cancellation the upload status becomes Cancelled and it no longer appears in the default query list.

Request

Params

Type	Name	Description	Required/Optional	Schema
path	upload_id	Upload id to cancel	required	integer
query	api	API type Available Values: destroy.by-default	required	enum

Request Example

DELETE /api/v202608/return-uploads/5678?api=destroy.by-default

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
upload_id	Upload id	integer
tracking_number	Tracking number	string
upload_status	Status (`Cancelled`)	string

Response Example

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "upload_id": 5678,
        "tracking_number": "9400111899223345678901",
        "upload_status": "Cancelled"
    }
}

GET /api/v202608/returns (Get return order list)

Two api variants:

index.by-default — Query your own company's return orders

index.by-unclaimed — Query unclaimed returns (including the cross-company public pool of unclaimed packages)

Return orders are read-only. They are auto-created when the warehouse scans the package at receiving; no write path is provided.

Request (`api = index.by-default`)

Params

Type	Name	Description	Required/Optional	Schema
query	api	API type Available Values: index.by-default	required	enum
query	return_id	Return order id	optional	integer
query	warehouse_id	Warehouse id	optional	integer
query	trx_id	Transaction id	optional	integer
query	return_from	Source filter (1/2/3)	optional	integer
query	tracking_number	Tracking number (fuzzy match)	optional	string
query	return_status	Return order processing status Available Values: Scanned: The warehouse has scanned the returned package and created the return order; not yet opened for inspection Verified: The warehouse has opened and counted the package; line item quantities and inventory `condition` have been verified and recorded Processed: Verified line items have been disposed of according to `return_action` (put away / disposal); the return order flow is complete Cancelled: The return order has been cancelled (warehouse-side exception scenarios such as mis-scans or duplicate scans)	optional	string
query	claim_status	Return order claim status. When the warehouse cannot automatically identify the owner from the line items (e.g. the tracking number does not match any upload in the system, or the SKU cannot be identified), the package enters the "pending claim" flow. Available Values: No Need: Already auto-matched to this company via upload or line items; no claim needed Unclaimed: The warehouse cannot yet identify the owner; awaiting the client to actively claim Claimed: The client has filed a claim application and is awaiting warehouse review Approved: Claim application approved; the package belongs to this client Rejected: Claim application rejected (e.g. insufficient evidence); the package remains in the pending-claim pool	optional	string
query	condition	Inventory condition of the returned line item, recorded row-by-row by the warehouse during inspection Available Values: New: Item is in like-new condition and can go directly to sellable inventory Damaged: Item is damaged and cannot be put back on the shelf for sale Stored: Received into stock but not yet classified as New or Damaged — intermediate state	optional	string
query	customer_sku	Filter by line-item SKU (return order returned when at least 1 line matches)	optional	string
query	fnsku	Filter by FNSKU	optional	string
query	lpn	Filter by LPN	optional	string
query	is_open	Line-item putaway status: 1: not yet put away, 0: already put away	optional	integer
query	created_at_from	Return order creation time from (approximately equal to warehouse scan time — most orders are created immediately at scan) Timezone: Pacific Standard Time	optional	datetime
query	created_at_to	Return order creation time to Timezone: Pacific Standard Time	optional	datetime
query	updated_at_from	Updated time from Timezone: Pacific Standard Time	optional	datetime
query	updated_at_to	Updated time to Timezone: Pacific Standard Time	optional	datetime
query	matched_upload_id	Filter by linked upload id	optional	integer
query	next_token	Token for the next page	optional	string

Request Example

GET /api/v202608/returns?api=index.by-default&warehouse_id=100&return_status=Verified&created_at_from=2026-08-01%2000:00:00&created_at_to=2026-08-31%2023:59:59

Request (`api = index.by-unclaimed`)

Fixed filters (cannot be overridden by the client):

Claim status = Unclaimed

Return order status ∈ (Verified, Processed)

Return order creation time within the most recent 7-day hard window (cannot be widened; the client may use created_at_from / created_at_to to narrow further within the window)

Results include this company's returns with unrecognized SKU + the platform-wide public pool of pending-claim packages

Type	Name	Description	Required/Optional	Schema
query	api	API type Available Values: index.by-unclaimed	required	enum
query	warehouse_id	Warehouse id	optional	integer
query	return_id	Return order id	optional	integer
query	trx_id	Transaction id	optional	integer
query	return_from	Source filter (1/2/3)	optional	integer
query	tracking_number	Tracking number (fuzzy match)	optional	string
query	customer_sku	Line-item SKU filter (used to identify your own packages)	optional	string
query	fnsku	FNSKU filter	optional	string
query	lpn	LPN filter	optional	string
query	condition	Line-item inventory condition Available Values: New / Damaged / Stored	optional	string
query	is_open	Line-item put-away flag: 1: not put away, 0: put away	optional	integer
query	created_at_from	Return order creation time from (only narrows within the 7-day hard window) Timezone: Pacific Standard Time	optional	datetime
query	created_at_to	Return order creation time to Timezone: Pacific Standard Time	optional	datetime
query	updated_at_from	Update time from Timezone: Pacific Standard Time	optional	datetime
query	updated_at_to	Update time to Timezone: Pacific Standard Time	optional	datetime
query	matched_upload_id	Filter by linked upload id	optional	integer
query	next_token	Token for the next page	optional	string

Note: return_status and claim_status cannot be customized in this variant — they are fixed by the server. All other line-item / dimension / date filters accept the same field names as index.by-default.

Request Example

GET /api/v202608/returns?api=index.by-unclaimed&warehouse_id=100&created_at_from=2026-08-07%2000:00:00&created_at_to=2026-08-14%2023:59:59&customer_sku=CUS-SKU-001

Response

Key	Value
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data Properties

Name	Description	Schema
return_id	Return order id	integer
warehouse_id	Warehouse id	integer
warehouse_name	Warehouse name	string
tracking_number	Tracking number	string
matched_upload_id	Linked upload id	integer
return_from	Source id	integer
return_from_name	Source display name	string
return_status	Return order processing status: Scanned: The warehouse has scanned the returned package and created the return order; not yet opened for inspection Verified: The warehouse has opened and counted the package; line items have been verified and recorded Processed: Verified line items have been disposed of according to `return_action` (put away / disposal); the return order flow is complete Cancelled: The return order has been cancelled (warehouse-side exception scenarios)	string
claim_status	Claim status. When the warehouse cannot automatically identify the owner from the line items, the package enters the pending-claim flow: No Need: Already auto-matched to this company via upload or line items; no claim needed Unclaimed: The warehouse cannot yet identify the owner; awaiting the client to actively claim Claimed: The client has filed a claim application and is awaiting warehouse review Approved: Claim application approved Rejected: Claim application rejected	string
trx_id	Transaction id	integer
ra_id	RA number	integer
notes	Notes	string
reason_code	Order-level reason code	string
expired_time	Expiration time Timezone: Pacific Standard Time	datetime
actual_finish_time	Actual finish time Timezone: Pacific Standard Time	datetime
scan_at / scan_by	Scan timestamp + operator	datetime / string
verify_at / verify_by	Verify timestamp + operator	datetime / string
processed_at	Finish time Timezone: Pacific Standard Time	datetime
return_items	Line items array	array
_scope	Returned only by `index.by-unclaimed`: `private` (own company but line-item SKU not recognized) / `public_pool` (cross-company public pool)	string
created_at	Created time Timezone: Pacific Standard Time	datetime
updated_at	Updated time Timezone: Pacific Standard Time	datetime

return_items sub-structure

Name	Description	Schema
return_detail_id	Line-item id	integer
customer_sku	Client SKU code	string
fnsku	Amazon FNSKU	string
lpn	LPN	string
expected_qty	Expected quantity	integer
verified_qty	Verified quantity	integer
put_away_qty	Put-away quantity	integer
condition	Inventory condition, recorded row-by-row by the warehouse during inspection: New: Item is in like-new condition and can go directly to sellable inventory Damaged: Item is damaged and cannot be put back on the shelf for sale Stored: Received into stock but not yet classified as New or Damaged — intermediate state	string
is_open	Putaway status: `1` = not yet put away, `0` = already put away	integer
reason_code	Line-item reason code	string
photos	Array of URLs of photos taken by the warehouse	array of string

Response Example (`index.by-default`)

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "return_id": 88888,
                "warehouse_id": 100,
                "warehouse_name": "SG-MDW1",
                "tracking_number": "1Z0A0000",
                "matched_upload_id": 5678,
                "return_from": 1,
                "return_from_name": "Buyer",
                "return_status": "Verified",
                "claim_status": "No Need",
                "trx_id": 33693018,
                "ra_id": null,
                "notes": "",
                "reason_code": null,
                "expired_time": "2026-11-14 00:00:00",
                "actual_finish_time": "2026-08-14 09:30:00",
                "scan_at": "2026-08-14 08:00:00", "scan_by": "warehouse_op_01",
                "verify_at": "2026-08-14 09:00:00", "verify_by": "warehouse_op_02",
                "processed_at": null,
                "return_items": [
                    {
                        "return_detail_id": 300001,
                        "customer_sku": "CUS-SKU-001",
                        "fnsku": null, "lpn": null,
                        "expected_qty": 1, "verified_qty": 1, "put_away_qty": 0,
                        "condition": "New",
                        "is_open": 1,
                        "reason_code": null,
                        "photos": ["https://cdn.shipsage.com/return/photo1.jpg"]
                    }
                ],
                "created_at": "2026-08-14 08:00:00",
                "updated_at": "2026-08-14 09:30:00"
            }
        ],
        "next_token": null
    }
}

Response Example (`index.by-unclaimed`)

{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "return_id": 99999,
                "warehouse_id": 100,
                "warehouse_name": "SG-MDW1",
                "tracking_number": "1Z0X0000",
                "return_status": "Verified",
                "claim_status": "Unclaimed",
                "actual_finish_time": "2026-08-12 15:00:00",
                "_scope": "public_pool",
                "return_items": [
                    { "return_detail_id": 400001, "customer_sku": "CUS-SKU-999", "condition": "New", "expected_qty": 1, "photos": [] }
                ],
                "created_at": "2026-08-12 14:30:00"
            }
        ],
        "next_token": null
    }
}

Endpoints#

Header#

GET /api/v202608/return-uploads (Get return-upload list)#

Request#

Params#

Request Example#

Response#

Data Properties#

expected_items sub-structure#

Response Example#

POST /api/v202608/return-uploads (Create return-uploads)#

Request#

Params#

return_uploads sub-structure#

expected_items sub-structure (all fields optional)#

Request Example#

Response#

Data Properties#

Response Example#

PUT /api/v202608/return-uploads/{upload_id} (Update a return-upload)#

Request#

Params#

Request Example#

Response#

Data Properties#

Response Example#

DELETE /api/v202608/return-uploads/{upload_id} (Cancel a return-upload)#

Request#

Params#

Request Example#

Response#

Data Properties#

Response Example#

GET /api/v202608/returns (Get return order list)#

Request (api = index.by-default)#

Params#

Request Example#

Request (api = index.by-unclaimed)#

Request Example#

Response#

Data Properties#

return_items sub-structure#

Response Example (index.by-default)#

Response Example (index.by-unclaimed)#

Endpoints

Header

GET /api/v202608/return-uploads (Get return-upload list)

Request

Params

Request Example

Response

Data Properties

expected_items sub-structure

Response Example

POST /api/v202608/return-uploads (Create return-uploads)

Request

Params

return_uploads sub-structure

expected_items sub-structure (all fields optional)

Request Example

Response

Data Properties

Response Example

PUT /api/v202608/return-uploads/{upload_id} (Update a return-upload)

Request

Params

Request Example

Response

Data Properties

Response Example

DELETE /api/v202608/return-uploads/{upload_id} (Cancel a return-upload)

Request

Params

Request Example

Response

Data Properties

Response Example

GET /api/v202608/returns (Get return order list)

Request (`api = index.by-default`)

Params

Request Example

Request (`api = index.by-unclaimed`)

Request Example

Response

Data Properties

return_items sub-structure

Response Example (`index.by-default`)

Response Example (`index.by-unclaimed`)