来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of Promotion, Account Health and Payment
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 1. Item-Level Promotion Limits
1. Item-Level Promotion Limits
Shopee has introduced an item-level promotion limit. Once an item reaches the predefined promotion limit, the system will prevent it from being added to new promotions.
- Affected APIs
The following promotion management APIs are impacted:
- v2.discount.add_discount_item
- v2.discount.update_discount_item
- v2.add_on_deal.add_add_on_deal_main_item
- v2.add_on_deal.add_add_on_deal_sub_item
- v2.add_on_deal.update_add_on_deal_main_item
- v2.add_on_deal.update_add_on_deal_sub_item
- v2.bundle_deal.add_bundle_deal_item
- v2.bundle_deal.update_bundle_deal_item
- Key Changes
- New Item-Level Promotion Limit & Error Handling: APIs will now validate the total number of promotions per item. If the limit is reached, APIs will block the operation and return the error: "The overall item level promotion limit has been reached."
§3 2. Account Health Metric Detail Updates
2. Account Health Metric Detail Updates
To help sellers better monitor their operational performance, Shopee has updated the v2.account_health.get_metric_source_detail API, as detailed below:
- Add new option: 4: Preparation Time for existing request parameter “metric_id”, and add new response parameter “apt_order_list” to retrieve affected parcels and their details for Preparation Time:
| Name | Type | Description |
|---|---|---|
| apt_order_list | object[] | Affected Parcels for Preparation Time. Supported metric_id: 4: Preparation Time |
| >>order_sn | string | Order SN |
| >>order_create_time | timestamp | Order Paid Time |
| >>arrange_pick_up_time | timestamp | Seller arrange pick up time |
| >>actual_pick_up_time | timestamp | Courier actual pick up time |
| >>preparation_days | float | Preparation Days |
| >>shipping_channel | string | Logistics Company |
| >>first_mile_type | string | First mile shipping type. Applicable values: Pickup Drop off |
| >>first_mile_tracking_no | string | Tracking No |
- Add the following new response parameters under the existing lsr_order_list:
| Name | Type | Description |
|---|---|---|
| lsr_order_list | object[] | Affected Orders for Late Shipment Rate. Supported metric_id: 1: Late Shipment Rate (All Channels) 85: Late Shipment Rate (NDD) |
| >>actual_pick_up_time | timestamp | Courier actual pick up time |
| >>shipping_channel | string | Logistics Company |
| >>first_mile_type | string | First mile shipping type. Applicable values: Pickup Drop off |
| >>diagnosis_scenario | string[] | Diagnosis of the issue |
- Add the following new response parameters under the existing fhr_order_list:
| Name | Type | Description |
|---|---|---|
| fhr_order_list | object[] | Affected Orders for Fast Handover Rate. Supported metric_id: 25: Fast Handover Rate 2001: Fast Handover Rate - SLS 2002: Fast Handover Rate - FBS 2003: Fast Handover Rate - 3PF |
| >>parcel_display_id | string | Display Parcel ID |
| >>fast_handover_due_date | timestamp | Fast Handover Due Date |
| >>arrange_pick_up_time | timestamp | Seller arrange pick up time. |
| >>shipping_channel | string | Logistics Company |
| >>first_mile_tracking_no | string | First Mile Tracking No. |
| >>first_mile_type | string | First mile shipping type. Applicable values: Pickup Drop off |
| >>diagnosis_scenario | string[] | Diagnosis of the issue |
Related APIs：
v2.account_health.get_metric_source_detail
Effective Date on Live：
2025.11.21
§4 3.New Response Field: fbs_fee in Escrow APIs
3.New Response Field: fbs_fee in Escrow APIs
To comply with the regulatory requirements of the Central Bank of the Philippines, we have added the response field “fbs_fee” to v2.payment.get_escrow_detail and v2.payment.get_escrow_detail_batch.
This enhancement enables PH FBS sellers to easily retrieve the Fulfilled by Shopee (FBS) fee associated with each order, including handling, storage, and packaging costs.
Related APIs：
v2.payment.get_escrow_detail
v2.payment.get_escrow_detail_batch
Effective Date on Live：
2025.11.12
尊敬的开发者，
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。
§5 1. 商品级促销限制
1. 商品级促销限制
Shopee 引入了商品级的促销数量上限。当商品参与的促销总数达到上限后，系统将阻止其被添加至新的促销中。
1）受影响接口
以下促销管理接口将受到影响：
- v2.discount.add_discount_item
- v2.discount.update_discount_item
- v2.add_on_deal.add_add_on_deal_main_item
- v2.add_on_deal.add_add_on_deal_sub_item
- v2.add_on_deal.update_add_on_deal_main_item
- v2.add_on_deal.update_add_on_deal_sub_item
- v2.bundle_deal.add_bundle_deal_item
- v2.bundle_deal.update_bundle_deal_item
2）主要变更
- 新增商品级促销限制与错误处理：接口将校验商品的促销总数，若达到数量上限，接口将禁止操作并返回错误信息："The overall item level promotion limit has been reached."
请确保您的应用程序能够妥善处理此错误，并引导卖家将商品从其他促销中移除后重试。
§6 2. Account Health 指标详情更新
2. Account Health 指标详情更新
为帮助卖家更好地监控运营表现，Shopee 对 v2.account_health.get_metric_source_detail 接口进行了更新，具体内容如下：
- 请求参数 metric_id 新增 4: Preparation Time 选项，并新增 apt_order_list 响应参数，以支持获取影响 Preparation Time 指标的包裹列表与详情：
| Name | Type | Description |
|---|---|---|
| apt_order_list | object[] | Affected Parcels for Preparation Time. Supported metric_id: 4: Preparation Time |
| >>order_sn | string | Order SN |
| >>order_create_time | timestamp | Order Paid Time |
| >>arrange_pick_up_time | timestamp | Seller arrange pick up time |
| >>actual_pick_up_time | timestamp | Courier actual pick up time |
| >>preparation_days | float | Preparation Days |
| >>shipping_channel | string | Logistics Company |
| >>first_mile_type | string | First mile shipping type. Applicable values: Pickup Drop off |
| >>first_mile_tracking_no | string | Tracking No |
- 已有响应参数 lsr_order_list 下新增以下响应参数：
| Name | Type | Description |
|---|---|---|
| lsr_order_list | object[] | Affected Orders for Late Shipment Rate. Supported metric_id: 1: Late Shipment Rate (All Channels) 85: Late Shipment Rate (NDD) |
| >>actual_pick_up_time | timestamp | Courier actual pick up time |
| >>shipping_channel | string | Logistics Company |
| >>first_mile_type | string | First mile shipping type. Applicable values: Pickup Drop off |
| >>diagnosis_scenario | string[] | Diagnosis of the issue |
- 已有响应参数 fhr_order_list 下新增以下响应参数：
| Name | Type | Description |
|---|---|---|
| fhr_order_list | object[] | Affected Orders for Fast Handover Rate. Supported metric_id: 25: Fast Handover Rate 2001: Fast Handover Rate - SLS 2002: Fast Handover Rate - FBS 2003: Fast Handover Rate - 3PF |
| >>parcel_display_id | string | Display Parcel ID |
| >>fast_handover_due_date | timestamp | Fast Handover Due Date |
| >>arrange_pick_up_time | timestamp | Seller arrange pick up time. |
| >>shipping_channel | string | Logistics Company |
| >>first_mile_tracking_no | string | First Mile Tracking No. |
| >>first_mile_type | string | First mile shipping type. Applicable values: Pickup Drop off |
| >>diagnosis_scenario | string[] | Diagnosis of the issue |
影响接口：
v2.account_health.get_metric_source_detail
上线时间：
2025.11.21
§7 3. Escrow 接口新增响应字段 fbs_fee
3. Escrow 接口新增响应字段 fbs_fee
为满足菲律宾中央银行的监管要求，我们在 v2.payment.get_escrow_detail 和 v2.payment.get_escrow_detail_batch 接口中新增了响应字段 fbs_fee。
该字段用于返回订单对应的 Shopee（FBS）费用，包括处理、仓储与包装等相关成本，便于菲律宾本地 FBS 卖家进行查询。
影响接口：
v2.payment.get_escrow_detail
v2.payment.get_escrow_detail_batch
上线时间：
2025.11.12