来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of Order, Returns, and Chat
Dear Developers
Please find below the OpenAPI updates released this time. These changes aim to enhance functionality, improve flexibility, and provide better integration support.
- Launch of Chat Message Duplication Control and CSAT Details Retrieval API
To further enhance chat quality and buyer experience, Shopee Open Platform has optimized its chat messaging and CSAT feedback features.
Updates include:
- Repetitive Message Blocking If a seller sends the same message within 24 hours, the second one will be blocked. API: v2.sellerchat.send_message
Error example:
- Negative CSAT Details Retrieval
New API: v2.chat.get_csat_details
Supports retrieving up to 20 messages sent before a negative CSAT evaluation within a specified time period, helping sellers review and improve service quality.
Affected APIs
v2.sellerchat.send_message
v2.sellerchat.get_csat_details
Effective Date
2025.10.14
- [Only for TW 30029 Logistics Channel] Support All Sorting Group Filter & Unpackaged SKU ID Label Displaying Sorting Group & Self-Designed Label Policy Update
To enhance sellers’ fulfillment experience when using the 30029 Logistics Channel, Shopee has implemented the following updates to order fulfillment related APIs:
-
v2.order.search_package_list: Add 0: All option to the existing sorting_group request parameter, allowing sellers to retrieve packages from all sorting groups at once. After this update, the supported options are 0: All, 1: North, 2: South.
-
v2.logistics.download_shipping_document: For packages shipped via the 30029 Logistics Channel, when printing the Unpackaged SKU ID Label (shipping_document_type = THERMAL_UNPACKAGED_LABEL), the top-right corner of the label now displays the sorting_group information to assist in sorting operations.
Sample of Unpackaged SKU ID Label:
- Update to Self-Designed "Unpackaged SKU ID Label" Policy: The font size for "unpackaged_sku_id" will be increased to at least 7 (must be fully displayed on the label), and the display area has been moved to the bottom of the label. This policy update will be effective on November 1, 2025. (The content of this announcement serves as a summary. For complete and accurate information, please refer to the FAQ document on Open Platform.)
Affected APIs
v2.order.search_package_list
v2.logistics.download_shipping_document
Effective Date
2025.09.30
- New Return Refund Request Type Identification and Reverse Logistics Tracking Information API
To optimize the seller's return management experience and address pain points such as the inability to distinguish between return refund request types and the inability to obtain logistics information for return packages, Shopee has implemented the following updates to return refund related APIs:
- v2.returns.get_return_list and v2.returns.get_return_detail: Add return_refund_request_type and validation_type response parameters to help sellers identify the return refund request type and the party responsible for inspecting the returned package. The logic is as follows:
| Name | Type | Description |
|---|---|---|
| return_refund_request_type | int | To indicate the type of return refund request: 0: Normal RR (RR is raised by the buyer after delivery done / estimated delivery date) 1: In-transit RR (RR is raised by the buyer while item is still in-transit to buyer) 2: Return-on-the-Spot (RR is raised by the driver after buyer rejected parcel at delivery) |
| validation_type | string | To indicate whether seller or warehouse will expect to receive the return parcel from buyer and validate the condition of the parcel: seller_validation warehouse_validation |
- Add new v2.returns.get_reverse_tracking_info API to help sellers obtain complete reverse logistics tracking information for a return refund request. The logic is as follows:
Request Parameters:
| Name | Type | Description |
|---|---|---|
| return_sn | string | Shopee's unique identifier for a return refund request. |
Main Response Parameters:
| Name | Type | Description |
|---|---|---|
| return_refund_request_type | int | To indicate the type of return refund request: 0: Normal RR (RR is raised by the buyer after delivery done / estimated delivery date) 1: In-transit RR (RR is raised by the buyer while item is still in-transit to buyer) 2: Return-on-the-Spot (RR is raised by the driver after buyer rejected parcel at delivery) |
| validation_type | string | To indicate whether seller or warehouse will expect to receive the return parcel from buyer and validate the condition of the parcel: seller_validation warehouse_validation |
| reverse_logistics_status | string | To indicate the latest reverse logistic status of a return, referring to the current status of the buyer shipping the return parcel back to the validation point (seller or warehouse). |
| reverse_logistics_update_time | timestamp | The last update time of the reverse logistics status including Normal RR, In-transit RR, and Return-on-the-Spot. |
| estimated_delivery_date_max | timestamp | The maximum estimated delivery date for the reverse logistics. This is calculated by Shopee Logistics Services once buyer ships out if there is historical tracking data available from third party logistics provider. Note: Only available for Normal RR with integrated reverse logistics. |
| estimated_delivery_date_min | timestamp | The minimum estimated delivery date for the reverse logistics. This is calculated by Shopee Logistics Services once buyer ships out if there is historical tracking data available from third party logistics provider. Note: Only available for Normal RR with integrated reverse logistics. |
| tracking_number | string | The tracking number for the reverse logistics (the logistics tracking number provided when the buyer ships the item back). Note: Only available for Normal RR with integrated reverse logistics. |
| tracking_info | object[] | The detailed tracking information list for the reverse logistics. Note: Only available for Normal RR with integrated reverse logistics. |
| >update_time | timestamp | The timestamps when reverse logistics info has been updated for Normal RR, pushed from third party logistics provider to Shopee. |
| >tracking_description | string | The description of reverse logistics tracking info for Normal RR, pushed by third party logistics provider to Shopee. |
| >epop_image_list | string[] | Image URLs of electronic proof of pickup (ePOP) after return parcel has been picked up from the buyer for Normal RR. |
| >epod_image_list | string[] | Image URLs of electronic proof of delivery (ePOD) after return parcel has been delivered to the seller for Normal RR. |
| post_return_logistics_status | string | Post-return logistics status, referring to the current status of the warehouse shipping the return parcel back to the seller in warehouse validation mode. Note: This information is only available for return/refund requests meeting all the following conditions: - return_refund_request_type = 0 (Normal RR) - return_solution = 0 (Return and Refund) - validation_type = warehouse_validation - The reverse logistics channel is integrated |
| post_return_logistics_update_time | timestamp | The last update time of the post-return logistics status where warehouse sends return parcel from warehouse to seller. Note: This information is only available for return/refund requests meeting all the following conditions: - return_refund_request_type = 0 (Normal RR) - return_solution = 0 (Return and Refund) - validation_type = warehouse_validation - The reverse logistics channel is integrated |
| rts_tracking_number | string | The tracking number for the post-return logistics (the logistics tracking number used when the warehouse ships the parcel back to the seller). RTS stands for "Return to Seller". Note: This information is only available for return/refund requests meeting all the following conditions: - return_refund_request_type = 0 (Normal RR) - return_solution = 0 (Return and Refund) - validation_type = warehouse_validation - The reverse logistics channel is integrated |
| post_return_logistics_tracking_info | object[] | The detailed tracking information list for the post-return logistics. Note: This information is only available for return/refund requests meeting all the following conditions: - return_refund_request_type = 0 (Normal RR) - return_solution = 0 (Return and Refund) - validation_type = warehouse_validation - The reverse logistics channel is integrated |
| >update_time | timestamp | The timestamps when reverse logistics info has been updated for Normal RR, pushed from third party logistics provider to Shopee. |
| >tracking_description | string | The description of reverse logistics tracking info for Normal RR, pushed by third party logistics provider to Shopee. |
| >epop_image_list | string[] | Image URLs of electronic proof of pickup (ePOP) after return parcel has been picked up from the warehouse for Normal RR with warehouse validation. |
| >epod_image_list | string[] | Image URLs of electronic proof of delivery (ePOD) after return parcel has been delivered to the seller for Normal RR with warehouse validation. |
Additional Notes:
- The reverse logistics logic differs depending on the return refund request type:
- If return_refund_request_type = 0 (Normal RR), the API will return the latest reverse logistics status, its update time, and complete reverse logistics tracking information.
- If return_refund_request_type = 1 (In-transit RR) or 2 (Return-on-the-Spot), the API will only return the latest reverse logistics status and its update time, without providing complete reverse logistics tracking information.
- Note: The values of reverse_logistics_status for In-transit RR and Return-on-the-Spot differ from those for Normal RR. For details, please refer to 3. Data Definition in Return Refund Management.
- The reverse logistics logic differs depending on the package validation type:
- If validation_type = seller_validation, there is only one segment of reverse logistics:
- The buyer ships the return parcel directly back to the seller. Use the fields reverse_logistics_status, reverse_logistics_update_time, tracking_number, and tracking_info to obtain the reverse logistics tracking information.
- If validation_type = warehouse_validation AND the warehouse uses an integrated logistics channel to ship the return parcel back to the seller, there are two segments of reverse logistics:
- The buyer first ships the return parcel back to the warehouse. Use the fields reverse_logistics_status, reverse_logistics_update_time, tracking_number, and tracking_info to obtain tracking information for this first segment.
- The warehouse then ships the return parcel back to the seller. Use the fields post_return_logistics_status, post_return_logistics_update_time, rts_tracking_number, and post_return_logistics_tracking_info to obtain tracking information for this second segment (post-return logistics).
- Note: For Cross-Border Returns, if the second segment exists, the API returns information for both the first and second segments. For Local Returns, if the second segment exists, the API prioritizes and returns only the second segment information.
- After the API update, the existing return_updates_push will synchronously support logistics_status update pushes for In-transit RR and Return-on-the-Spot. Among these, the values of logistics_status for In-transit RR and Return-on-the-Spot differ from those for Normal RR. For details, please refer to 3. Data Definition in Return Refund Management.
Affected APIs
v2.returns.get_return_list
v2.returns.get_return_detail
v2.returns.get_reverse_tracking_info
Affected Pushs
return_updates_push
Effective Date
2025.09.30
尊敬的开发者
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。
- 新增聊天消息防重复机制与CSAT详情查询接口
为提升聊天服务质量与买家体验，Shopee Open Platform 对消息发送及售后反馈能力进行了优化升级。
本次更新包括：
1）消息发送内容优化
若卖家在24小时内重复发送相同内容的消息，第二条重复消息将被拦截。
API：v2.sellerchat.send_message
错误返回示例：
2）买家满意度反馈接口 新增API：v2.chat.get_csat_details 支持在指定时间范围内，查询买家给予负向评价（Bad CSAT）前的最多20条聊天记录，帮助卖家分析并改进服务质量。
影响接口
v2.sellerchat.send_message
v2.sellerchat.get_csat_details
生效日期
2025.10.14
2.【仅适用于 TW 30029 物流渠道】支持 All 分拣组筛选 & 虾皮商品编码标签展示分拣组信息 & 自画标签规范更新
为提升卖家使用 30029 物流渠道的履约体验，Shopee对订单履约相关接口进行了以下更新：
1）v2.order.search_package_list：在现有的 sorting_group 请求参数中新增 0: All 选项，卖家可一次性获取所有分拣组的包裹信息。更新后，该参数支持的选项为 0: All、1: North、2: South
2）v2.logistics.download_shipping_document：针对使用 30029 物流渠道发货的包裹，当打印虾皮商品编码标签 (shipping_document_type = THERMAL_UNPACKAGED_LABEL) 时，标签右上角将新增展示 sorting_group 信息，以协助分拣操作。
虾皮商品编码标签示例：
- 自画 “虾皮商品编码” 标签规范更新：“unpackaged_sku_id” 的字体规范变更为大于等于 7 号 (需在标签上完整显示)，并将显示区域移至标签底部。此规范将于 2025年11月1日 生效。(本公告所述内容仅供参考，实际规范请以开放平台上的 FAQ 文档为准。)
影响接口
v2.order.search_package_list
v2.logistics.download_shipping_document
生效日期
2025.09.30
- 新增退货退款请求类型识别与逆向物流跟踪信息接口
为优化卖家的退货管理体验，解决卖家无法区分退货退款请求类型、无法获取退货包裹的物流信息等痛点，Shopee对退货退款相关接口进行了以下更新：
1）v2.returns.get_return_list 与 v2.returns.get_return_detail：新增 return_refund_request_type、validation_type 响应参数，帮助卖家识别退货退款请求类型与包裹验货方，逻辑如下：
| Name | Type | Description |
|---|---|---|
| return_refund_request_type | int | 用于标识退货退款请求的类型： 0：普通退货 (Normal RR，买家在包裹送达后或超过预计送达日期后发起的退货退款请求) 1：在途退货 (In-transit RR，买家在商品仍在运输途中时发起的退货退款请求) 2：当场退货 (Return-on-the-Spot，配送员在买家拒收包裹后发起的退货退款请求) |
| validation_type | string | 用于标识将由哪一方接收退货包裹并验证其状况： seller_validation：卖家验证 warehouse_validation：仓库验证 |
2）新增 v2.returns.get_reverse_tracking_info 接口，帮助卖家获取退货请求的完整逆向物流跟踪信息，逻辑如下：
请求参数：
| Name | Type | Description |
|---|---|---|
| return_sn | string | Shopee退货退款请求的唯一标识符 |
主要响应参数：
| Name | Type | Description |
|---|---|---|
| return_refund_request_type | int | 退货退款请求类型： 0：普通退货 (Normal RR，买家在包裹签收后或超过预计送达日期后发起的退货退款请求) 1：在途退货 (In-transit RR，买家在商品仍在运输途中时发起的退货退款请求) 2：当场退货 (Return-on-the-Spot，配送员在买家拒收包裹后发起的退货退款请求) |
| validation_type | string | 包裹验证类型，标识将由哪一方接收退货包裹并验证其状况： seller_validation：卖家验证 warehouse_validation：仓库验证 |
| reverse_logistics_status | string | 逆向物流状态，指买家将退货包裹寄回到验证点 (卖家或仓库) 的当前状态 |
| reverse_logistics_update_time | timestamp | 逆向物流状态的最后更新时间 |
| estimated_delivery_date_max | timestamp | 逆向物流的最晚预计送达时间 注：此信息仅适用于使用集成物流渠道的普通退货 (Normal RR) |
| estimated_delivery_date_min | timestamp | 逆向物流的最早预计送达时间 注：此信息仅适用于使用集成物流渠道的普通退货 (Normal RR) |
| tracking_number | string | 逆向物流的运单号 (买家寄回的物流追踪号) 注：此信息仅适用于使用集成物流渠道的普通退货 (Normal RR) |
| tracking_info | object[] | 逆向物流的详细跟踪信息列表 注：此信息仅适用于使用集成物流渠道的普通退货 (Normal RR) |
| >update_time | timestamp | 单条物流跟踪信息的更新时间 |
| >tracking_description | string | 单条物流跟踪信息的文字描述 |
| >epop_image_list | string[] | 电子取件证明 (ePOP) 的图片URL列表 |
| >epod_image_list | string[] | 电子签收证明 (ePOD) 的图片URL列表 |
| post_return_logistics_status | string | 退货后物流状态，指仓库验证模式下，仓库将退货包裹寄回给卖家的当前状态 注：此信息仅适用于同时满足以下条件的退货退款请求： - return_refund_request_type = 0 (Normal RR) - return_solution = 0 (Return and Refund) - validation_type = warehouse_validation - The reverse logistics channel is integrated |
| post_return_logistics_update_time | timestamp | 退货后物流状态的最后更新时间 注：此信息仅适用于同时满足以下条件的退货退款请求： - return_refund_request_type = 0 (Normal RR) - return_solution = 0 (Return and Refund) - validation_type = warehouse_validation - The reverse logistics channel is integrated |
| rts_tracking_number | string | 退货后物流的运单号 (仓库寄回给卖家的物流追踪号) 注：此信息仅适用于同时满足以下条件的退货退款请求： - return_refund_request_type = 0 (Normal RR) - return_solution = 0 (Return and Refund) - validation_type = warehouse_validation - The reverse logistics channel is integrated |
| post_return_logistics_tracking_info | object[] | 退货后物流的详细跟踪信息列表 注：此信息仅适用于同时满足以下条件的退货退款请求： - return_refund_request_type = 0 (Normal RR) - return_solution = 0 (Return and Refund) - validation_type = warehouse_validation - The reverse logistics channel is integrated |
| >update_time | timestamp | 单条物流跟踪信息的更新时间 |
| >tracking_description | string | 单条物流跟踪信息的文字描述 |
| >epop_image_list | string[] | 电子取件证明 (ePOP) 的图片URL列表 |
| >epod_image_list | string[] | 电子签收证明 (ePOD) 的图片URL列表 |
补充说明：
1）不同退货退款请求类型对应的逆向物流逻辑不同，逻辑如下：
- 若 return_refund_request_type = 0 (Normal RR)，则接口会返回最新的逆向物流状态及其更新时间，以及完整的逆向物流跟踪信息
- 若 return_refund_request_type = 1 (In-transit RR) 或 2 (Return-on-the-Spot)，则接口只会返回最新的逆向物流状态及其更新时间，不会返回完整的逆向物流跟踪信息
- 注：In-transit RR、Return-on-the-Spot 的 reverse_logistics_status 枚举值，和 Normal RR 的 reverse_logistics_status 枚举值不同，详情请参考 Return Refund Management 中的 3.Data Definition
2）不同包裹验证类型对应的逆向物流逻辑不同，逻辑如下：
- 若 validation_type = seller_validation，则只有一段逆向物流:
- 买家直接将退货包裹寄回到卖家，请使用reverse_logistics_status、reverse_logistics_update_time、tracking_number、tracking_info字段，来获取逆向物流跟踪信息
- 若 validation_type = warehouse_validation 且仓库使用集成物流渠道将退货包裹寄回给卖家，则有两段逆向物流：
- 买家先将退货包裹寄回到仓库，请使用reverse_logistics_status、reverse_logistics_update_time、tracking_number、tracking_info字段，来获取逆向物流跟踪信息
- 仓库再将退货包裹寄回给卖家，请使用post_return_logistics_status、post_return_logistics_update_time、rts_tracking_number、post_return_logistics_tracking_info字段，来获取退货后物流跟踪信息
- 注：针对跨境退货 (CB RR)，若存在第二段物流，则接口同时返回第一段与第二段物流信息，针对本地退货 (Local RR)，若存在第二段物流，则接口优先且仅返回第二段物流信息
3）接口更新后，原有的 return_updates_push 将同步支持 In-transit RR 和 Return-on-the-Spot 类型的 logistics_status 更新推送，其中 In-transit RR、Return-on-the-Spot 的 reverse_logistics_status 枚举值，和 Normal RR 的 logistics_status 枚举值不同，详情请参考 Return Refund Management 中的 3.Data Definition
影响接口
v2.returns.get_return_list
v2.returns.get_return_detail
v2.returns.get_reverse_tracking_info
影响推送
return_updates_push
生效日期
2025.09.30