来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of Logistics, Order, Payment, Product
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. Support Advance Fulfilment for Multi-Warehouse Sellers
1. Support Advance Fulfilment for Multi-Warehouse Sellers
To support multi-warehouse sellers in using the Advance Fulfilment feature, Shopee has upgraded the relevant Open API, enabling sellers to accurately obtain the warehouse address for each item in Advance Fulfilment orders via API, thus avoiding shipping errors caused by address mismatches.
- In the v2.order.get_booking_detail, the product_location_id response parameter will return the actual fulfillment warehouse for each item in the Advance Fulfillment order, helping sellers accurately match item stock with the fulfillment warehouse.
| Name | Type | Description |
|---|---|---|
| product_location_id | string | The actual fulfillment warehouse ID corresponding to each item in the Advance Fulfilment order. Note: This field previously returned an empty value; in this upgrade, it will return the specific warehouse ID (this only applies to sellers with multiple warehouses). |
-
In the v2.logistics.get_booking_shipping_parameter, the pickup.address_list response parameter will return the system-recommended warehouse addresses for the Advance Fulfilment order. The recommended warehouse address ID must be used when arranging shipments.
-
In the v2.logistics.ship_booking, the pickup.address_id request parameter only supports the system-recommended warehouse address ID obtained via the v2.logistics.get_booking_shipping_parameter .
Note: If a non-recommended address ID is provided, the shipment cannot be completed, and the following error will be returned: “Pickup address is not supported.”
Related APIs
v2.order.get_booking_detail
v2.logistics.get_booking_shipping_parameter
v2.logistics.ship_booking
Effective Date on Live
April 1, 2026
§3 2.Supports configuring channel’s "Auto Call Driver" toggle and its "Preparation Time"
2.Supports configuring channel’s "Auto Call Driver" toggle and its "Preparation Time"
Shopee has launched the “Auto Call Driver” feature for Instant delivery channels in ID, MY, VN, and TH regions. This feature allows the system to automatically arrange shipment and trigger driver dispatch while the seller is preparing the package. Once the package is ready, the system will immediately trigger driver dispatch without any manual operation. Please refer to the previous announcement for more details.
This update aims to supplement and optimize the "Auto Call Driver" function, allowing sellers to configure the "Auto Call Driver" toggle and its "Preparation Time" for logistics channels via Open API. The API updates are as follows:
- v2.logistics.get_channel_list adds the following response parameter to support retrieving “Auto Call Driver” related information for the channel.
| Name | Type | Description |
|---|---|---|
| auto_call_driver_setting | object | / |
| -> auto_call_driver_eligible | boolean | Indicate whether this channel is eligible for Auto Call Driver. |
| -> auto_call_driver_enabled | boolean | Indicate whether Auto Call Driver is currently enabled for this channel. |
| -> preparation_time | int32 | The current valid preparation time for this channel, in minutes. |
| -> preparation_time_limit | object | The preparation time range allowed for this channel.Note: When calling v2.logistics.update_channel to set the Preparation Time for the channel, the time must not exceed this range. |
| -> -> min_preparation_time | int32 | The minimum allowable preparation time, in minutes. |
| -> -> max_preparation_time | int32 | The maximum allowable preparation time, in minutes. |
- v2.logistics.update_channel adds the following request and response parameters, allowing sellers to configure the “Auto Call Driver” toggle and its “Preparation Time” for the channel.
| Name | Type | Description |
|---|---|---|
| auto_call_driver_setting | object | / |
| -> auto_call_driver_enabled | boolean | Whether to enable Auto Call Driver for this logistic channel. |
| -> preparation_time | int32 | Used to set the Preparation Time for this channel, in minutes. Required when auto_call_driver_enabled = true. Note: Please ensure the passed preparation_time value falls within the preparation_time_limit range returned by v2.logistics.get_channel_list. |
Additionally, the v2.logistics.update_channel interface adds the following error messages to more accurately locate “Auto Call Driver” configuration issues:
| Error Msg | Description / Solution |
|---|---|
| Seller or Channel does not support Auto-Call. | The current shop or selected channel does not support the Auto Call Driver function. To avoid this error, please call v2.logistics.get_channel_list to get channel details before calling the update API. Setting auto_call_driver_eligible = true is only allowed if the response parameter auto_call_driver_enabled = true. |
| Invalid Auto-Call setting param. | The auto_call_driver_setting object in the request contains invalid data or is missing required fields. Common causes include: 1. The required field auto_call_driver_enabled is missing. 2. When auto_call_driver_enabled is set to true, the required preparation_time is not provided. Please check the request parameters to ensure that all fields are complete and valid. |
| Invalid Seller preparation time. | The set preparation_time exceeds the valid range allowed for this channel. To avoid this error, the value passed for preparation_time must fall within the preparation_time_limit range returned by v2.logistics.get_channel_list, i.e., between min_preparation_time and max_preparation_time. |
Note:
When calling v2.logistics.update_channel to configure the “Auto Call Driver” toggle, there may still be a cache delay of up to 10 minutes:
- Enable: After enabling, packages that newly transition to “LOGISTICS_READY” status will be automatically arranged for shipment. Packages that were already in “LOGISTICS_READY” status before enabling will still require manual shipment arrangement.
- Disable: After disabling, packages that newly transition to “LOGISTICS_READY” status will require manual shipment arrangement. Packages that transitioned before disabling may still be automatically arranged.
- The driver_status response parameter in v2.order.get_package_detail has added a new enumeration value: Driver should arrive by {starting_time - end_time}, indicating the estimated time range for the driver to arrive for pickup.
| Name | Type | Description |
|---|---|---|
| driver_status | string | Driver status. Applicable values: - Allocating Driver - Driver assigned - Driver should arrive by {starting_time - end_time} - Driver is on the way - Driver is arrived |
Related APIs
v2.logistics.get_channel_list
v2.logistics.update_channel
v2.order.get_package_detail
Effective Date on Live
April 10, 2026
§4 3. Instant Orders Support “Pause/Resume” Function
3. Instant Orders Support “Pause/Resume” Function
To help sellers more flexibly handle order peaks and fulfillment pressure, and improve the stability of instant delivery services and seller experience, Shopee is launching the Instant Orders Pause/Resume function.
Through this function, sellers can temporarily stop receiving new instant orders, the fulfillment of existing orders will not be affected. When the daily pause quota is exhausted or the seller manually resumes, order reception will automatically/immediately resume.
Applicable Regions: MY, TH, VN, ID, PH, BR.
- v2.logistics.get_channel_list adds the support_pause response parameter to indicate whether the channel supports pause operations.
| Name | Type | Description |
|---|---|---|
| support_pause | boolean | Indicates whether this channel supports the pause operation (Pausing allows the shop to temporarily prevent buyers from placing orders through this logistics channel). - true: This channel is affected by the pause function. - false: This channel is not affected by the pause function. Note: Please first call v2.logistics.get_pause_status to get the current pause status of logistics channels under the shop. If is_paused = true, then call v2.logistics.get_channel_list and identify the range of channels affected by the pause function through support_pause = true. |
- Add v2.logistics.get_pause_status API to query the shop's current instant order pause status, estimated end time, and remaining daily pause quota information.
| Name | Type | Description |
|---|---|---|
| is_paused | boolean | Indicate the current pause status of logistics channels under the shop. Applicable values: - true: All relevant channels are currently paused and will not have any new incoming orders - false: No channels are paused and may have new incoming orders Note: Please first call v2.logistics.get_pause_status to query the current suspension status of instant orders for the store. If is_paused = true, then call v2.logistics.get_channel_list and identify the range of channels affected by the pause function through support_pause = true. |
| pause_end_time | timestamp | Time at which the relevant paused channels will automatically resume, returned only when is_paused = true, indicating the estimated time when the system will automatically resume order acceptance after the daily remaining quota is exhausted. Note: During the pause period, the seller may call the v2.logistics.set_pause_status at any time with is_paused = false to manually resume order acceptance. After resumption, the consumption of the daily remaining quota will stop and it will be retained until reset the next day. |
| remaining_pause_quota | int64 | The remaining pause quota of the shop on the current day, in seconds, returned only when is_paused = false. |
- Add v2.logistics.set_pause_status API to actively set the store's instant order pause or resume status.
Request Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
| is_paused | boolean | True | The target pause status that seller wants to update to. Applicable values: - true: Trigger pause. All relevant channels will be paused and will not have any new incoming orders (fulfillment of existing orders will not be affected). Meanwhile, the system will start deducting the daily pause quota and automatically calculate the pause end time based on the remaining quota. - false: Trigger manual resume. No channels are paused and may have new incoming orders. The remaining daily quota will stop being consumed and be retained until reset the next day. Note: Due to the system cache synchronization mechanism, there may be an approximately 15-second delay before the pause/resume operation takes effect. It is recommended to call the v2.logistics.get_pause_status for confirmation after the update. |
Response Parameters:
| Name | Type | Description |
|---|---|---|
| is_paused | boolean | Indicate the current pause status of logistics channels under the shop. Applicable values: - true: All relevant channels are currently paused and will not have any new incoming orders - false: No channels are paused and may have new incoming orders Note: Please first call v2.logistics.get_pause_status to query the current suspension status of instant orders for the store. If is_paused = true, then call v2.logistics.get_channel_list and identify the range of channels affected by the pause function through support_pause = true. |
| pause_end_time | timestamp | Time at which the relevant paused channels will automatically resume, returned only when is_paused = true, indicating the estimated time when the system will automatically resume order acceptance after the daily remaining quota is exhausted. Note: During the pause period, the seller may call the v2.logistics.set_pause_status at any time with is_paused = false to manually resume order acceptance. After resumption, the consumption of the daily remaining quota will stop and it will be retained until reset the next day. |
| remaining_pause_quota | int64 | The remaining pause quota of the shop on the current day, in seconds, returned only when is_paused = false. |
Related APIs
v2.logistics.get_channel_list
v2.logistics.get_pause_status
v2.logistics.set_pause_status
Effective Date on Live
April 10, 2026
§5 4.[ID]Mandatory max_purchase_limit for Category 100119
4.[ID]Mandatory max_purchase_limit for Category 100119
Background
To comply with regulatory requirements, Shopee will introduce a remote consultation flow for pharmaceutical-related products. Accordingly, OpenAPI will enforce validation on the maximum purchase quantity per order for items under the specified category.
Scope
ID local sellers only
Affected Categories
When creating or updating items via OpenAPI under the following category, the field max_purchase_limit will be mandatory and must represent the maximum quantity per order:
| Category ID | Category Name |
|---|---|
| 100119 | Health > Medicine & Medical Supplies > Over-the-counter Medicine |
Under category 100119, if max_purchase_limit is not provided, an error will occur: For OTC medicine, maximum purchase limit per order is mandatory and cannot exceed 3 days of use.
Affected APIs
v2.product.add_item
v2.product.update_item
Effective Date
April 10, 2026
§6 5.ShopeeVIP Fee Included in Payment API Fields
5.ShopeeVIP Fee Included in Payment API Fields
Background
To enhance user experience and expand the user base, Shopee now supports subscribing to ShopeeVIP via Cash on Delivery (COD).
To support this capability, OpenAPI has updated the Payment-related API response structure, allowing ShopeeVIP fees to be reflected in settlement data.
Region
ID, VN, TH, PH, TW, MY
Affected APIs
v2.payment.get_escrow_detail
v2.payment.get_escrow_detail_batch
New Field
| Field Path | Description |
|---|---|
| buyer_payment_info > shopeevip_subtotal | The subscription fee paid by the buyer for ShopeeVIP. |
- The field shopeevip_subtotal will always be returned in the response, even if its value is 0.
Updated Field
order_income > buyer_total_amount now includes the ShopeeVIP fee.
Effective Date
April 9, 2026
§7 6.Notification of Deprecation for promotion_id Field
6.Notification of Deprecation for promotion_id Field
The removal of the promotion_id field from the v2.product.get_item_base_info interface, as mentioned in the previous announcement, has been scheduled. This field will be deprecated on May 8, 2026.
To retrieve details of promotional activities that a product participates in, please use the v2.product.get_item_promotion interface instead.
尊敬的开发者
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。
§8 1. 支持多仓卖家使用预先履约功能
1. 支持多仓卖家使用预先履约功能
为支持多仓卖家使用预先履约功能，Shopee 对预先履约相关 Open API 进行了能力升级，支持卖家通过 API 准确获取预先履约订单中各商品对应的发货仓库地址，避免因地址不匹配导致发货异常。
1）v2.order.get_booking_detail 接口的 product_location_id 响应参数将返回预先履约订单中各商品对应的实际履约仓库，便于卖家精准匹配商品库存与发货仓库。
| Name | Type | Description |
|---|---|---|
| product_location_id | string | 预订履约订单中商品对应的实际履约仓库 ID 注意：该字段在此前版本中返回为空，本次升级后将返回具体的仓库 ID (仅对多仓卖家生效) |
2）v2.logistics.get_booking_shipping_parameter 接口的 pickup.address_list 响应参数将返回系统为该预先履约订单推荐的仓库地址，后续发货时需传入该推荐仓库地址 ID。
3）v2.logistics.ship_booking 接口的 pickup.address_id 请求参数，仅支持传入通过 v2.logistics.get_booking_shipping_parameter 接口获取的系统推荐仓库地址 ID。
注意：传入非推荐地址 ID，将无法完成发货，并返回错误提示：Pickup address is not supported.
影响接口
v2.order.get_booking_detail
v2.logistics.get_booking_shipping_parameter
v2.logistics.ship_booking
上线时间
2026 年 4 月 1 日
§9 2. 支持配置渠道的 “Auto Call Driver” 开关及其 “Preparation Time”
2. 支持配置渠道的 “Auto Call Driver” 开关及其 “Preparation Time”
Shopee 已针对 ID, MY, VN, TH 市场的即时配送渠道推出 “Auto Call Driver” 功能，该功能可在卖家准备订单期间自动发货并调度配送司机，实现订单准备就绪后立即触发派单，无需手动操作，详情参考此前公告。
本次更新旨在对 “Auto Call Driver” 功能进行补充优化，支持卖家通过 Open API 配置物流渠道的 “Auto Call Driver” 开关及其 “Preparation Time”，接口更新如下：
1）v2.logistics.get_channel_list 新增以下响应参数，支持获取渠道的 “Auto Call Driver” 相关信息。
| Name | Type | Description |
|---|---|---|
| auto_call_driver_setting | object | / |
| -> auto_call_driver_eligible | boolean | 标识该渠道是否支持开启 Auto Call Driver |
| -> auto_call_driver_enabled | boolean | 标识该渠道当前是否已开启 Auto Call Driver |
| -> preparation_time | int32 | 该渠道当前生效的准备时间，单位为分钟 |
| -> preparation_time_limit | object | 该渠道允许设置的准备时间范围注意：卖家在调用 v2.logistics.update_channel 设置渠道的 Preparation Time 时，不可超出此范围 |
| -> -> min_preparation_time | int32 | 允许设置的最短准备时间，单位为分钟 |
| -> -> max_preparation_time | int32 | 允许设置的最长准备时间，单位为分钟 |
2）v2.logistics.update_channel 新增以下请求参数和响应参数，支持卖家配置渠道的 Auto Call Driver 开关及其 Preparation Time。
| Name | Type | Description |
|---|---|---|
| auto_call_driver_setting | object | / |
| -> auto_call_driver_enabled | boolean | 用于开启或关闭该渠道的 Auto Call Driver 开关 |
| -> preparation_time | int32 | 用于设置该渠道的 Preparation Time，单位为分钟，当 auto_call_driver_enabled = true 时必填 注意：请确保传入的 preparation_time 值位于 v2.logistics.get_channel_list 返回的 preparation_time_limit 区间内 |
此外，v2.logistics.update_channel 接口新增以下错误信息，用于更精准地定位 “Auto Call Driver” 配置问题：
| Error Msg | Description / Solution |
|---|---|
| Seller or Channel does not support Auto-Call. | 当前店铺或所选渠道不支持 Auto Call Driver 功能 为避免此报错，请在调用更新接口前，先调用 v2.logistics.get_channel_list 查询渠道详情，仅当响应参数 auto_call_driver_eligible = true 时，才允许设置 auto_call_driver_enabled = true |
| Invalid Auto-Call setting param. | 请求中的 auto_call_driver_setting 对象包含无效数据或缺少必要字段。常见原因包括： 1. 缺少必填字段 auto_call_driver_enabled 2. 当设置 auto_call_driver_enabled = true 时，未同时提供必需的 preparation_time 请检查请求参数，确保字段完整且合法 |
| Invalid Seller preparation time. | 设置的 preparation_time 超出了该渠道允许的有效范围 为避免此报错，请确保传入的 preparation_time 值位于 v2.logistics.get_channel_list 返回的 preparation_time_limit 区间内，即介于 min_preparation_time 和 max_preparation_time 之间 |
注意：
调用 v2.logistics.update_channel 为渠道设置 Auto Call Driver 切换仍存在最多 10 分钟的缓存延迟：
- 开启：开启后新变为 “LOGISTICS_READY” 状态的包裹将自动发货，在此之前已处于 “LOGISTICS_READY” 状态的包裹，卖家仍需手动安排发货；
- 关闭：关闭后新变为 “LOGISTICS_READY” 状态的包裹需手动安排发货，在此之前变为 “LOGISTICS_READY” 状态的包裹仍可能触发自动发货。
3）v2.order.get_package_detail 中的 driver_status 响应参数，新增枚举值 Driver should arrive by {starting_time - end_time}，表示司机预计在此时间范围内到达取货。
| Name | Type | Description |
|---|---|---|
| driver_status | string | 司机状态，枚举值如下： - Allocating Driver - Driver assigned - Driver should arrive by {starting_time - end_time} - Driver is on the way - Driver is arrived |
影响接口
v2.logistics.get_channel_list
v2.logistics.update_channel
v2.order.get_package_detail
上线时间
2026 年 4 月 10 日
§10 3. 即时订单支持“暂停/恢复”功能
3. 即时订单支持“暂停/恢复”功能
为帮助卖家更灵活地应对订单高峰与履约压力，提升即时配送服务的稳定性与卖家经营体验，Shopee 推出 Instant 订单暂停/恢复功能。
通过该功能，卖家可以临时停止接收新的即时订单，已产生的订单履约不受影响；当日暂停额度使用完毕或卖家手动恢复后，订单接收将自动/即时恢复。
适用范围：MY、TH、VN、ID、PH、BR。
1）v2.logistics.get_channel_list 新增 support_pause 响应参数，用于标识该渠道是否支持暂停操作。
| Name | Type | Description |
|---|---|---|
| support_pause | boolean | 标识该渠道是否支持暂停操作true：该渠道受暂停功能影响，触发暂停时，该渠道将同步停止接收新订单false：该渠道不受暂停功能影响注意：请先调用 v2.logistics.get_pause_status 查询店铺即时订单的当前暂停状态，若 is_paused = true，再调用 v2.logistics.get_channel_list，通过 support_pause = true 识别受暂停功能影响的渠道范围 |
2）新增 v2.logistics.get_pause_status 接口，用于查询店铺即时订单的当前暂停状态、预计恢复时间、当日剩余暂停配额等信息。
| Name | Type | Description |
|---|---|---|
| is_paused | boolean | 标识该店铺即时订单的当前暂停状态 true：已暂停，平台将暂停分配新即时订单 false：正常接单中 注意：请先调用 v2.logistics.get_pause_status 查询店铺即时订单的当前暂停状态，若 is_paused = true，再调用 v2.logistics.get_channel_list，通过 suppor_pause = true 识别受暂停功能影响的渠道范围 |
| pause_end_time | timestamp | 自动恢复接单的时间戳，仅当 is_paused = true 时返回，表示当日剩余配额耗尽后系统自动恢复接单的预计时间 注意：卖家可在暂停期间的任意时刻调用 v2.logistics.set_pause_status 接口传入 is_paused = false 手动恢复接单，恢复后当日剩余配额将停止消耗并保留至次日重置 |
| remaining_pause_quota | int64 | 店铺当日剩余暂停时长，单位为秒，仅当 is_paused = false 时返回 |
3）新增 v2.logistics.set_pause_status 接口，用于主动设置店铺即时订单为暂停或恢复状态。
请求参数：
| Name | Type | Required | Description |
|---|---|---|---|
| is_paused | boolean | True | 店铺即时订单的目标暂停状态 true：触发暂停，平台将暂停分配新即时订单 (已产生的订单履约不受影响)，同时系统开始扣除当日暂停配额，并基于剩余配额自动计算恢复时间 false：触发手动恢复，恢复接收即时订单，当日剩余配额将停止消耗并保留至次日重置 注意：由于系统缓存同步机制，暂停/恢复操作生效可能存在约 15秒 的延迟，建议更新后调用 v2.logistics.get_pause_status 接口确认 |
响应参数：
| Name | Type | Description |
|---|---|---|
| is_paused | boolean | 标识该店铺即时订单的当前暂停状态 true：已暂停，平台将暂停分配新即时订单 false：正常接单中 注意：请先调用 v2.logistics.get_pause_status 查询店铺即时订单的当前暂停状态，若 is_paused = true，再调用 v2.logistics.get_channel_list，通过 suppor_pause = true 识别受暂停功能影响的渠道范围 |
| pause_end_time | int64 | 自动恢复接单的时间戳，仅当 is_paused = true 时返回，表示当日剩余配额耗尽后系统自动恢复接单的预计时间 注意：卖家可在暂停期间的任意时刻调用 v2.logistics.set_pause_status 接口传入 is_paused = false 手动恢复接单，恢复后当日剩余配额将停止消耗并保留至次日重置 |
| remaining_pause_quota | int64 | 店铺当日剩余暂停时长，单位为秒，仅当 is_paused = false 时返回 |
影响接口
v2.logistics.get_channel_list
v2.logistics.get_pause_status
v2.logistics.set_pause_status
上线时间
2026 年 4 月 10 日
§11 4.[ID] 药品类目（100119）开启max_purchase_limit必填校验
4.[ID] 药品类目（100119）开启max_purchase_limit必填校验
背景
为满足监管要求，Shopee 将上线药品相关商品的远程问诊流程。 本次更新将对指定类目（100119）下商品的每订单最大购买数量进行强制校验。
适用范围
仅适用于 ID 本地卖家（ID local sellers）
适用场景
当卖家通过 OpenAPI 在以下类目下创建或更新商品时，字段 max_purchase_limit 将变为必填项，且需填写每个订单最大购买数量：
| 类目 ID | 类目名称 |
|---|---|
| 100119 | Health > Medicine & Medical Supplies > Over-the-counter Medicine |
在类目100119下，如果未传max_purchase_limit 将会报错：For OTC medicine, maximum purchase limit per order is mandatory and cannot exceed 3 days of use.
影响接口
v2.product.add_item
v2.product.update_item
上线时间
2026年4月10日
§12 5.payment系列接口字段包含ShopeeVIP 费用
5.payment系列接口字段包含ShopeeVIP 费用
背景
为提升用户体验并拓展用户群体，Shopee 支持通过 货到付款（COD） 方式开通 ShopeeVIP。
为支持 ShopeeVIP 通过货到付款（COD）方式完成订阅，OpenAPI对 Payment 相关接口返回结构进行更新，使 ShopeeVIP 费用能够在结算数据中体现。
适用范围
ID、VN、TH、PH、TW、MY
涉及接口
v2.payment.get_escrow_detail v2.payment.get_escrow_detail_batch
新增字段
| 字段路径 | 字段说明 |
|---|---|
| buyer_payment_info > shopeevip_subtotal | 买家支付的 ShopeeVIP 订阅费用。 |
*字段 shopeevip_subtotal 在返回结果中始终返回，即使其值为 0。
变更字段 order_income > buyer_total_amount已包含ShopeeVIP 费用。
生效日期
2026年4月9日
§13 6.promotion_id字段下线通知
6.promotion_id字段下线通知
在之前公告中提到的v2.product.get_item_base_info上的promotion_id字段下线事项现已确定好下线时间，该字段将于2026年5月8号下线，若需获取商品参与的促销活动详情，请使用接口 v2.product.get_item_promotion