来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of Return
Dear Developers
Please find below the OpenAPI updates released this time. These changes aim to enhance functionality, improve flexibility, and provide better integration support.
§2 Add New Warehouse Handling Fields to Return APIs
Business Background
In return and refund scenarios, when validation_type = warehouse_validation, the buyer will ship the return parcel to Shopee’s local warehouse. If the parcel meets the return policy, the warehouse will then ship the parcel back to the seller.
Although sellers can already use the v2.returns.get_reverse_tracking_info to track the parcel’s logistics journey from “Buyer → Local Warehouse” and “Local Warehouse → Seller” (see section “3. New Return Refund Request Type Identification and Reverse Logistics Tracking Information API” for details), the parcel’s handling process inside the warehouse is still not visible to sellers. For example, sellers cannot see whether the parcel has been successfully inbounded or rejected by the warehouse, and whether it will be returned to them, making it difficult to accurately assess the parcel’s current status.
Therefore, this API update adds new fields related to the warehouse handling stage, enabling sellers to fully understand how return parcels are handled within the warehouse.
API Update Details
Affected APIs:
New Response Fields:
| Name | Type | Description |
|---|---|---|
| is_arrived_at_warehouse | int32 | Indicates the parcel’s check-in status at the warehouse. This field helps sellers quickly determine whether the parcel has arrived at the warehouse or has been rejected. Applicable values: 1: Pending Inbound 2: Rejected 3: Inbound 4: Cancelled Note: [Only for validation_type = warehouse_validation] |
| follow_up_action_list | object[] | Warehouse handling actions for each item in the parcel. Note: [Only for validation_type = warehouse_validation] |
| >>item_id | int64 | Unique identifier of the item. |
| >>model_id | int64 | Unique identifier of the model under the item. |
| >>qty | int32 | Quantity of items or models under the same current status. |
| >>current_status | int32 | Current status for the item/model within the warehouse. Applicable values: 1：Dispose 2：Return to Seller 7：Received and Putaway 8：Return to Buyer 9：Shortage Note: Since Resell is currently applicable only to Failed Delivery parcels, the following values will not be returned for now, and will be returned once Resell becomes applicable to Return Refund parcels in the future: 3：Putaway for Resell 4：Resell Outbound 5：Resell Failed 6：Resell Exit |
| >>related_order_sn_list | string[] | List of order_sn generated from the Resell process. Returned only when current_status = 4 (Resell Outbound). Note: Since Resell is currently applicable only to Failed Delivery parcels, this field will remain empty for now, and valid values will be returned once Resell becomes applicable to Return Refund parcels in the future. |
| >>resell_failed_next_step | string | Next step after a Resell failure. Returned only when current_status = 5 (Resell Failed). Note: Since Resell is currently applicable only to Failed Delivery parcels, this field will remain empty for now, and valid values will be returned once Resell becomes applicable to Return Refund parcels in the future. |
Effective Date
2025.11.24
尊敬的开发者
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。
§3 Return API 新增仓库处理字段
业务背景
在退货退款场景中，若 validation_type = warehouse_validation，买家会将退货包裹寄回 Shopee 的当地退货仓库，若符合退运条件，仓库再将退货包裹寄回给卖家。
尽管卖家可以通过已有的 v2.returns.get_reverse_tracking_info 接口，查询退货包裹在 “买家 → 当地仓” 与 “当地仓 → 卖家” 的物流轨迹 (详情参考 “3. 新增退货退款请求类型识别与逆向物流跟踪信息接口” 部分)，但是退货包裹在仓库内的处理流程仍然不可见，例如：包裹是否已成功入仓或被仓库拒收、是否会退回卖家等，导致卖家难以准确判断包裹现状。
因此，本次 API 更新将补充仓库处理阶段相关字段，使卖家能够完整了解退货包裹在仓库内的处理状态。
接口更新内容
影响 API：
新增字段说明：
| Name | Type | Description |
|---|---|---|
| is_arrived_at_warehouse | int32 | 包裹在仓库的入仓状态，可通过该字段快速判断包裹是否到达仓库或被拒收。 枚举值： 1：待入仓 2：被驳回 3：已入仓 4：已取消 注：仅适用于 validation_type = warehouse_validation |
| follow_up_action_list | object[] | 包裹中每个商品在仓库的处理动作列表，用于展示仓库逐项处理情况。 注：仅适用于 validation_type = warehouse_validation |
| >>item_id | int64 | 商品的唯一标识。 |
| >>model_id | int64 | 商品下变体的唯一标识。 |
| >>qty | int32 | 处于同一状态的商品或变体数量。 |
| >>current_status | int32 | 当前商品或变体的仓库处理结果状态。 可用枚举值： 1：Dispose (已处置) 2：Return to Seller (退回卖家) 7：Received and Putaway (接收并入库) 8：Return to Buyer (退回买家) 9：Shortage (缺货) 注：由于 Resell (二次销售) 目前仅适用于 Failed Delivery 包裹，不适用于 Return Refund 包裹，因此以下枚举值暂时不会返回，待后续 Resell 适用于 Return Refund 包裹后才会返回： 3：Putaway for Resell (入库待二次销售) 4：Resell Outbound (二次销售出库) 5：Resell Failed (二次销售失败) 6：Resell Exit (二次销售退出) |
| >>related_order_sn_list | string[] | 二次销售的订单列表，当 current_status = 4 (Resell Outbound) 时返回。 注：同上，由于 Resell (二次销售) 目前仅适用于 Failed Delivery 包裹，不适用于 Return Refund 包裹，因此该字段将返回为空，待后续 Resell 适用于 Return Refund 包裹后才会返回有效值。 |
| >>resell_failed_next_step | string | 二次销售失败后的下一步操作，当 current_status = 5 (Resell Failed) 时返回。 注：同上，由于 Resell (二次销售) 目前仅适用于 Failed Delivery 包裹，不适用于 Return Refund 包裹，因此该字段将返回为空，待后续 Resell 适用于 Return Refund 包裹后才会返回有效值。 |
生效日期
2025.11.24