退货 - Help for ShipSage

端点

方法	端点	描述
GET	/api/v202608/return-uploads	获取退货预报列表
POST	/api/v202608/return-uploads	创建退货预报（批量提交）
PUT	/api/v202608/return-uploads/{upload_id}	更新退货预报（仅 Pending 状态可改）
DELETE	/api/v202608/return-uploads/{upload_id}	取消退货预报
GET	/api/v202608/returns	获取退货主单列表（本公司）
GET	/api/v202608/returns	获取待认领退货列表（`index.by-unclaimed`）

[新增] v202608 新增接口（2026-09 补丁）：以上 6 个退货接口均为本次新增，v202206 未提供。
概念区分：
退货预报 (return-upload)：客户端通过 API 创建的"这些 tracking 会退回来"的声明
退货主单 (return)：仓库入库扫描时自动创建；客户端只读
仓库扫到对应 tracking 时预报状态转为 Matched，同时自动创建主单

头部

键	值
Authorization	Bearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...

GET /api/v202608/return-uploads （获取退货预报列表）

请求

参数

类型	名称	描述	必填/选填	数据结构
query	api	API 类型可用值: index.by-default	必填	enum
query	upload_id	预报 id	选填	integer
query	tracking_number	运单号（模糊匹配）	选填	string
query	return_from	来源过滤： 1：Buyer, 2：FBA, 3：Third-Party	选填	integer
query	reference_id	客户自定义的参考号，用于关联客户系统内部的单据。创建预报时可传原始出库单号、RMA 号、客户订单号等任意字符串（不做唯一性校验），此处按精确值过滤	选填	string
query	upload_status	预报状态可用值: Pending：等待仓库扫描匹配 Matched：仓库已扫描到对应包裹并创建退货主单 Cancelled：客户主动取消 Expired：超过 90 天未匹配，系统自动过期	选填	enum
query	matched	是否已匹配 Return 主单（`true` = 只返回 Matched；`false` = 排除 Matched）	选填	boolean
query	created_at_from	创建时间起时区：太平洋标准时间	选填	datetime
query	created_at_to	创建时间止时区：太平洋标准时间	选填	datetime
query	updated_at_from	更新时间起时区：太平洋标准时间	选填	datetime
query	updated_at_to	更新时间止时区：太平洋标准时间	选填	datetime
query	next_token	下一页数据的秘钥	选填	string

请求示例

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

键	值
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data properties

名称	描述	数据结构
upload_id	预报 id	integer
tracking_number	运单号	string
return_from	来源 id	integer
return_from_name	来源显示名（`Buyer` / `FBA` / `Third Party`）	string
reference_id	客户自定义参考号（如原始出库单号、RMA 号、订单号等）	string
return_action	处置方式可用值: Putaway：上架, Disposal：销毁	string
upload_status	预报状态： Pending：等待仓库扫描匹配 Matched：仓库已扫描到对应包裹并创建退货主单 Cancelled：客户主动取消 Expired：超过 90 天未匹配，系统自动过期	string
matched_return_id	命中后关联的 Return 主单 id（未匹配为 null）	integer
matched_at	匹配时间（对应 Return 主单创建时间）时区：太平洋标准时间	datetime
expected_items	预期明细数组	array
expires_at	过期时间（默认创建后 90 天）时区：太平洋标准时间	datetime
created_at	创建时间时区：太平洋标准时间	datetime
updated_at	更新时间时区：太平洋标准时间	datetime

expected_items 子结构

名称	描述	数据结构
customer_sku	客户 sku 编码	string
fnsku	Amazon FNSKU	string
lpn	LPN	string
qty	预期数量	integer
notes	备注	string

返回示例

{
    "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 （创建退货预报）

批量提交，all-or-nothing：任一 tracking 校验失败，整批拒绝。

请求

参数

类型	名称	描述	必填/选填	数据结构
query	api	API 类型可用值: store.by-default	必填	enum
body	return_uploads	预报数组	必填	array

return_uploads 子结构

名称	描述	必填/选填	数据结构
tracking_number	运单号（不能为空；批次内不能重复）	必填	string
return_from	来源可用值: 1：Buyer, 2：FBA, 3：Third-Party	选填	enum
reference_id	参考号	选填	string
return_action	处置方式可用值: Putaway（默认）, Disposal	选填	enum
expected_items	预期明细数组（可空）	选填	array

expected_items 子结构（每项字段全部可选）

名称	描述	必填/选填	数据结构
customer_sku	客户 sku 编码	选填	string
fnsku	Amazon FNSKU	选填	string
lpn	LPN	选填	string
qty	预期数量	选填	integer
notes	备注	选填	string

请求示例

{
    "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": "客户改变主意退货" }
            ]
        },
        {
            "tracking_number": "9400111899223345678902",
            "return_from": 2,
            "reference_id": "RMA-FBA-20260807-A",
            "return_action": "Disposal"
        }
    ]
}

键	值
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data properties

名称	描述	数据结构
return_uploads	生成的预报数组，每项含 `upload_id` + `tracking_number`（用于回查映射）	array

返回示例

{
    "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} （更新退货预报）

仅 Pending 状态可更新（Matched 后不可修改）。tracking_number 是匹配定位键不可修改。

Partial update 语义：只有客户端显式传的字段才写入，未传的字段保留原值。expected_items 传入时整体替换（不是增量合并）。

请求

参数

类型	名称	描述	必填/选填	数据结构
path	upload_id	目标预报 id	必填	integer
query	api	API 类型可用值: update.by-default	必填	enum
body	return_from	来源	选填	integer
body	reference_id	参考号	选填	string
body	return_action	处置方式（`Putaway` / `Disposal`）	选填	enum
body	expected_items	明细数组（整体替换）	选填	array

注：需要修改运单号时，请先取消旧预报，再创建新预报。

请求示例

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": "客户改数量" }
    ]
}

键	值
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data properties

名称	描述	数据结构
upload_id	预报 id	integer
tracking_number	运单号	string

返回示例

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

DELETE /api/v202608/return-uploads/{upload_id} （取消退货预报）

仅 Pending 状态可取消。取消后预报状态转为 Cancelled，同时不再出现在默认查询列表中。

请求

参数

类型	名称	描述	必填/选填	数据结构
path	upload_id	要取消的预报 id	必填	integer
query	api	API 类型可用值: destroy.by-default	必填	enum

请求示例

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

键	值
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data properties

名称	描述	数据结构
upload_id	预报 id	integer
tracking_number	运单号	string
upload_status	状态（`Cancelled`）	string

返回示例

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

GET /api/v202608/returns （获取退货主单列表）

两种 api：

index.by-default —— 查询本公司主单

index.by-unclaimed —— 查询待认领（含跨公司公共池的未认领包裹）

退货主单只读，由仓库入库扫描时自动创建，不提供写路径。

请求（`api = index.by-default`）

参数

类型	名称	描述	必填/选填	数据结构
query	api	API 类型可用值: index.by-default	必填	enum
query	return_id	主单 id	选填	integer
query	warehouse_id	仓库 id	选填	integer
query	trx_id	交易号	选填	integer
query	return_from	来源过滤（1/2/3）	选填	integer
query	tracking_number	运单号（模糊匹配）	选填	string
query	return_status	退货主单处理状态可用值: Scanned：仓库已扫描到退回包裹并创建主单，尚未开箱验货 Verified：仓库已开箱清点，明细数量与库存状态（`condition`）已核对录入 Processed：验货明细已按 `return_action` 完成处置（上架 / 销毁），主单流程结束 Cancelled：主单已取消（仓库端异常场景，如误扫、重复扫描等）	选填	string
query	claim_status	退货主单认领状态。当仓库无法从明细自动识别归属方（例如运单号未在系统内匹配到预报，或 SKU 未识别）时，包裹会进入"待认领"流程可用值: No Need：已通过预报或明细自动匹配到本公司，无需认领 Unclaimed：仓库暂无法识别归属，待客户主动认领 Claimed：客户已发起认领申请，等待仓库审核 Approved：认领申请审核通过，包裹归属该客户 Rejected：认领申请被拒绝（例如凭证不符），包裹仍在待认领池	选填	string
query	condition	退回商品明细的库存状态，由仓库验货时逐行录入可用值: New：商品完好如新，可直接进入可售库存 Damaged：商品有损坏，不能上架销售 Stored：已归入库存但未判定为 New 或 Damaged 的中间状态	选填	string
query	customer_sku	按明细 SKU 过滤（主单至少 1 行匹配才返回）	选填	string
query	fnsku	按 FNSKU 过滤	选填	string
query	lpn	按 LPN 过滤	选填	string
query	is_open	明细上架状态： 1：未上架, 0：已上架	选填	integer
query	created_at_from	主单创建时间起（约等于仓库入库扫描时间——绝大多数主单在扫描时立即建单）时区：太平洋标准时间	选填	datetime
query	created_at_to	主单创建时间止时区：太平洋标准时间	选填	datetime
query	updated_at_from	更新时间起时区：太平洋标准时间	选填	datetime
query	updated_at_to	更新时间止时区：太平洋标准时间	选填	datetime
query	matched_upload_id	按关联预报 id 过滤	选填	integer
query	next_token	下一页数据的秘钥	选填	string

请求示例

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

请求（`api = index.by-unclaimed`）

固定过滤（客户端不能覆盖）：

认领状态 = Unclaimed

主单状态 ∈ (Verified, Processed)

主单创建时间在最近 7 天硬性窗口 内（不可扩宽；客户端可用 created_at_from / created_at_to 在窗口内进一步收窄）

结果包含本公司未识别 SKU 的退货 + 全平台公共池待认领包裹

类型	名称	描述	必填/选填	数据结构
query	api	API 类型可用值: index.by-unclaimed	必填	enum
query	warehouse_id	仓库 id	选填	integer
query	return_id	主单 id	选填	integer
query	trx_id	交易号	选填	integer
query	return_from	来源过滤（1/2/3）	选填	integer
query	tracking_number	运单号（模糊匹配）	选填	string
query	customer_sku	按明细 SKU 过滤（用于识别自己的包裹）	选填	string
query	fnsku	按 FNSKU 过滤	选填	string
query	lpn	按 LPN 过滤	选填	string
query	condition	退回商品明细的库存状态可用值: New / Damaged / Stored	选填	string
query	is_open	明细上架状态： 1：未上架, 0：已上架	选填	integer
query	created_at_from	主单创建时间起（只能在 7 天硬性窗口内进一步收窄）时区：太平洋标准时间	选填	datetime
query	created_at_to	主单创建时间止时区：太平洋标准时间	选填	datetime
query	updated_at_from	更新时间起时区：太平洋标准时间	选填	datetime
query	updated_at_to	更新时间止时区：太平洋标准时间	选填	datetime
query	matched_upload_id	按关联预报 id 过滤	选填	integer
query	next_token	下一页数据的秘钥	选填	string

注：return_status 与 claim_status 在此变体下不可自定义，由服务端固定；其他明细/维度/日期过滤都与 index.by-default 同源，接受相同的字段名。

请求示例

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

键	值
errcode	0/4000
errmsg	ok/Error Info
data	Data Properties

Data properties

名称	描述	数据结构
return_id	主单 id	integer
warehouse_id	仓库 id	integer
warehouse_name	仓库名	string
tracking_number	运单号	string
matched_upload_id	关联预报 id	integer
return_from	来源 id	integer
return_from_name	来源显示名	string
return_status	退货主单处理状态： Scanned：仓库已扫描到退回包裹并创建主单，尚未开箱验货 Verified：仓库已开箱清点，明细已核对录入 Processed：验货明细已按 `return_action` 完成处置（上架 / 销毁），主单流程结束 Cancelled：主单已取消（仓库端异常场景）	string
claim_status	认领状态。当仓库无法从明细自动识别归属方时进入待认领流程： No Need：已通过预报或明细自动匹配到本公司，无需认领 Unclaimed：仓库暂无法识别归属，待客户主动认领 Claimed：客户已发起认领申请，等待仓库审核 Approved：认领申请审核通过 Rejected：认领申请被拒绝	string
trx_id	交易号	integer
ra_id	RA 号	integer
notes	备注	string
reason_code	主单原因码	string
expired_time	过期时间时区：太平洋标准时间	datetime
actual_finish_time	实际完成时间时区：太平洋标准时间	datetime
scan_at / scan_by	Scan 时间戳 + 操作人	datetime / string
verify_at / verify_by	Verify 时间戳 + 操作人	datetime / string
processed_at	完成时间时区：太平洋标准时间	datetime
return_items	明细数组	array
_scope	仅 `index.by-unclaimed` 返回：`private`（本公司但明细 SKU 未识别）/ `public_pool`（跨公司公共池）	string
created_at	创建时间时区：太平洋标准时间	datetime
updated_at	更新时间时区：太平洋标准时间	datetime

return_items 子结构

名称	描述	数据结构
return_detail_id	明细行 id	integer
customer_sku	客户 sku 编码	string
fnsku	Amazon FNSKU	string
lpn	LPN	string
expected_qty	预期数量	integer
verified_qty	已验数量	integer
put_away_qty	已上架数量	integer
condition	库存状态，由仓库验货时逐行录入： New：商品完好如新，可直接进入可售库存 Damaged：商品有损坏，不能上架销售 Stored：已归入库存但未判定为 New 或 Damaged 的中间状态	string
is_open	上架状态：`1` = 未上架，`0` = 已上架	integer
reason_code	明细行原因码	string
photos	仓库拍摄照片 URL 数组	array of string

返回示例（`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
    }
}

返回示例（`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
    }
}

退货

端点#

头部#

GET /api/v202608/return-uploads （获取退货预报列表）#

请求#

参数#

请求示例#

返回#

Data properties#

expected_items 子结构#

返回示例#

POST /api/v202608/return-uploads （创建退货预报）#

请求#

参数#

return_uploads 子结构#

expected_items 子结构（每项字段全部可选）#

请求示例#

返回#

Data properties#

返回示例#

PUT /api/v202608/return-uploads/{upload_id} （更新退货预报）#

请求#

参数#

请求示例#

返回#

Data properties#

返回示例#

DELETE /api/v202608/return-uploads/{upload_id} （取消退货预报）#

请求#

参数#

请求示例#

返回#

Data properties#

返回示例#

GET /api/v202608/returns （获取退货主单列表）#

请求（api = index.by-default）#

参数#

请求示例#

请求（api = index.by-unclaimed）#

请求示例#

返回#

Data properties#

return_items 子结构#

返回示例（index.by-default）#

返回示例（index.by-unclaimed）#

端点

头部

GET /api/v202608/return-uploads （获取退货预报列表）

请求

参数

请求示例

返回

Data properties

expected_items 子结构

返回示例

POST /api/v202608/return-uploads （创建退货预报）

请求

参数

return_uploads 子结构

expected_items 子结构（每项字段全部可选）

请求示例

返回

Data properties

返回示例

PUT /api/v202608/return-uploads/{upload_id} （更新退货预报）

请求

参数

请求示例

返回

Data properties

返回示例

DELETE /api/v202608/return-uploads/{upload_id} （取消退货预报）

请求

参数

请求示例

返回

Data properties

返回示例

GET /api/v202608/returns （获取退货主单列表）

请求（`api = index.by-default`）

参数

请求示例

请求（`api = index.by-unclaimed`）

请求示例

返回

Data properties

return_items 子结构

返回示例（`index.by-default`）

返回示例（`index.by-unclaimed`）