来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of Payment, OpenPlatform, Product, Order
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.【BR Only】Update on BR Shopee Voucher Fee Deduction Logic
1.【BR Only】Update on BR Shopee Voucher Fee Deduction Logic
To further improve tax calculation accuracy and financial data consistency, Shopee Voucher will be used to offset commission and service fees before tax calculation and will be included in fee discount calculation.
Applicable Scope
BR local shops
The v2.payment.get_escrow_detail / v2.payment.get_escrow_detail_batchinterfaces have added a new field: remaining_voucher, which indicates the amount of Shopee Voucher that remains unused after fee deduction. When there is no remaining Shopee Voucher, the default value is 0. This field is only returned when the value is greater than 0.
| Type | Field Name | Description |
|---|---|---|
| New Field | remaining_voucher | Remaining Shopee Voucher amount after fee deduction. Default value is 0 when there is no remaining Shopee Voucher. This field will only be returned when the value is greater than 0. |
Affected APIs:
v2.payment.get_escrow_detail
v2.payment.get_escrow_detail_batch
Effective Date:
Lived
§3 2. Instant Mart Project Launch Notice
2. Instant Mart Project Launch Notice
Background
Instant Mart is a special shop structure designed for retailers that require both centralized headquarters management and independent outlet operations.
Under this model:
Mart Shop (official primary shop) acts as the headquarters and is responsible for global SKU management, item creation, and financial reporting
Outlet Shop represents physical stores and is responsible for daily operations such as order processing, inventory management, and item packing
Through Open API integration, Instant Mart merchants can choose to:
Manage SKUs centrally at the merchant level (shared across all outlets)
Or manage SKUs independently at the outlet level (maintained separately by each outlet)
Before integrating with Open API, merchants must complete Mart Merchant and Outlet Shop onboarding in the BDC Portal and ensure the shops are registered as Instant Mart Shops.
After setup is completed, developers can build solutions supporting the full Instant Mart operational flow through Open API integration.
Applicable Scope
The Instant Mart project is now officially available in ID, PH, TH, MY, VN, and BR.
Developers may refer to the Instant Mart Integration Guide for the overall business model and API integration logic.
Effective Date:
Lived
§4 3. Adjustment to Logistics Fields Returned in v2.product.update_item
3. Adjustment to Logistics Fields Returned in v2.product.update_item
Background
Currently, after calling the v2.product.update_itemAPI to update item logistics channels, the logistics status returned in the response may not reflect the latest actual status in a timely manner due to the cache mechanism.
For example, after enabling certain logistics channels through update_item, the response may still indicate that the channels are disabled, while v2.product.get_item_base_info already shows the channels as enabled.
To avoid developers making business decisions based on cached data, Shopee plans to gradually deprecate logistics-related fields in the response of v2.product.update_item.
Update Details
Starting from 2026/06/15:
Logistics-related fields will no longer be returned in the response of v2.product.update_item
Logistics parameters in the update_item request will remain supported
The API will continue processing logistics update operations normally
To retrieve the latest logistics information, please call v2.product.get_item_base_info
Shopee is also evaluating further optimization of the update_item response structure. Related arrangements will be announced separately.
Effective Date:
2026.06.15
§5 4. New Partial Order Cancellation Capability
To help sellers continue fulfilling orders when some items are out of stock, Shopee Open API will support partial order cancellation. After the update, eligible sellers can cancel only the out-of-stock items in an order and continue shipping the remaining items.
This feature will be gradually rolled out first in TH.
The updates are as follows:
- The v2.order.get_order_detail and v2.order.get_package_detail APIs will return whether an order supports full cancellation, partial cancellation, and the buyer’s out-of-stock handling preference.
| Name | Type | Description |
|---|---|---|
| can_full_cancel_order | boolean | Indicates whether the order can be full cancelled: - If this value is true, seller can cancel the entire order - If the value is false, full order cancellation is not available for the order |
| can_partial_cancel_order | boolean | Indicates whether the order is eligible for partial cancellation. This value is determined by both the system eligibility check and the buyer’s out-of-stock handling preference. - If this value is true, seller can cancel selected out-of-stock item quantities while continuing to fulfill the remaining items. - If this value is false, partial cancellation is not allowed. |
| buyer_preference_for_partial_cancellation | int64 | Indicates the buyer’s preference for handling out-of-stock items in the order. Applicable values: 0 = Ship Available Items Only (The buyer allows the seller to cancel unavailable items and continue shipping the remaining available items) 1 = Cancel The Entire Order (The buyer does not allow partial cancellation. If any item is unavailable, the seller should cancel the entire order instead) |
- To help sellers accurately distinguish item quantity status and identify the cancellable quantity of each item, the v2.order.get_order_detail API will add the following fields.
| Name | Type | Description |
|---|---|---|
| item_list | object[] | This object contains the detailed breakdown for the result of this API call. |
| >>active_qty | int32 | The quantity of the item model that remains active in the order and is still expected to be fulfilled. |
| >>cancel_requested_qty | int32 | The quantity of the item model that is currently under a cancellation request but has not yet reached the final cancelled status. |
| >>cancelled_qty | int32 | The quantity of the item model that has already been successfully cancelled. |
| >>return_requested_qty | int32 | The quantity of the item model that is currently under a return/refund request. |
| >>returned_qty | int32 | The quantity of the item model that has already been successfully returned through the return/refund process. |
- The v2.order.cancel_order API will support partial cancellation. Sellers can specify the items and quantities to be cancelled in the request.
| Name | Type | Description |
|---|---|---|
| order_sn | string | Shopee's unique identifier for an order. |
| cancel_reason | string | The reason seller want to cancel this order. |
| partial_cancel_item_list | object[] | The list of item models and quantities that the seller wants to partially cancel. This field should be provided when the seller intends to cancel only part of the order due to unavailable items while continuing to fulfill the remaining items. |
| >>item_id | int64 | The unique identifier of the item to be partially cancelled. |
| >>model_id | int64 | The unique identifier of the model to be partially cancelled. |
| >>order_item_id | int64 | The identify of order item. For items in one same bundle deal promotion, the order_item_id should share the same id, such as 1,2. For items not in bundle deal promotion, the order_item_id should be the same as item_id. |
| >>promotion_group_id | int64 | The identify of product promotion.It's required for add on deal and bundle deal items. For items in one same add on deal or bundle deal promotion, the promotion_group_id should share the same id. For items not in add on deal or bundle deal promotion, the promotion_group_id should be 0. And the data is from promotion_group_id of v2,order.get_order_detail. |
| >>model_quantity | int64 | The quantity of the specified item model to be cancelled. |
Note: If v2.order.get_order_detail returns can_partial_cancel_order as false; the call will fail.
- Shopee will add a new API, v2.order.get_estimiate_cancel_value, allowing sellers to query the estimated cancellation amount before submitting a partial cancellation request.
Request parameters:
| Name | Type | Description |
|---|---|---|
| order_sn | string | Unique Shopee order identifier. |
| partial_cancel_item_list | object[] | The list of item models and quantities for which the seller wants to estimate the cancellation value before submitting the actual partial cancellation request. |
| >>item_id | int64 | The unique identifier of the item to be included in the estimated cancellation value calculation. |
| >>model_id | int64 | The unique identifier of the model to be included in the estimated cancellation value calculation. |
| >>order_item_id | int64 | The identify of order item. For items in one same bundle deal promotion, the order_item_id should share the same id, such as 1,2. For items not in bundle deal promotion, the order_item_id should be the same as item_id. |
| >>promotion_group_id | int64 | The identify of product promotion.It's required for add on deal and bundle deal items. For items in one same add on deal or bundle deal promotion, the promotion_group_id should share the same id. For items not in add on deal or bundle deal promotion, the promotion_group_id should be 0. And the data is from promotion_group_id of v2,order.get_order_detail. |
| >>model_quantity | int64 | The quantity of the specified item model to be included in the estimated cancellation value calculation. |
Response parameters:
| Name | Type | Description |
|---|---|---|
| cancel_value | int64 | The estimated cancellation value for the selected item quantities. This value is calculated before the actual cancellation is submitted and can be used by sellers to preview the expected cancellation amount and support partial cancellation confirmation. |
Related APIs:
v2.order.get_order_detail
v2.order.get_package_detail
v2.order.cancel_order
v2.order.get_estimate_cancel_value
Effective Date on Live:
2026.05.22
尊敬的开发者
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。
§6 1. 【BR Only】BR Shopee Voucher 费用抵扣逻辑更新
为进一步提升税务计算准确性及财务数据一致性，Shopee Voucher 将在税费计算前用于抵扣佣金及服务费，纳入费用折扣计算。
适用范围：BR local shop
v2.payment.get_escrow_detail / v2.payment.get_escrow_detail_batch新增字段，remaining_voucher表示在费用抵扣后未被消耗的 Shopee Voucher 金额。当不存在剩余 Shopee Voucher 时，默认值为 0。该字段仅在值大于 0 时返回。
| 类型 | 字段名 | 说明 |
|---|---|---|
| 新增字段 | remaining_voucher | 表示在费用抵扣后未被消耗的 Shopee Voucher 金额。当不存在剩余 Shopee Voucher 时，默认值为 0。该字段仅在值大于 0 时返回。 |
影响接口：
v2.payment.get_escrow_detail
v2.payment.get_escrow_detail_batch
上线时间：
Lived
§7 2. Instant Mart 项目上线通知
背景
Instant Mart 是一种特殊的店铺结构，用于支持同时具备总部统一管理与门店独立运营能力的零售商。
在该模式下：
Mart Shop（官方主店）作为总部角色，负责管理全局 SKU、创建商品及查看财务报表
Outlet Shop（分店）代表实际门店，负责订单处理、库存维护及商品打包等日常运营
通过 Open API 集成，Instant Mart 商家可根据业务需求选择：
在 merchant 层级统一管理 SKU（所有 outlet 共享）
或在 outlet 层级独立管理 SKU（各门店独立维护）
在接入 Open API 前，商家需先在 BDC Portal 完成 Mart Merchant 与 Outlet Shop 入驻，并注册为 Instant Mart Shop。
完成配置后，开发者即可基于 Open API 构建支持 Instant Mart 全链路运营的解决方案。
适用范围
Instant Mart 项目现已正式上线 ID、PH、TH、MY、VN、BR 站点。
开发者可参考Instant Mart Integration Guide，了解整体业务模式及相关接口逻辑。
上线时间：
Lived
§8 3. v2.product.update_item 接口物流字段返回调整
背景
当前调用v2.product.update_item 接口更新商品物流渠道后，由于缓存机制影响，response 中返回的物流渠道状态可能无法及时反映最新实际状态。
例如，开发者通过 update_item 启用部分物流渠道后，response 中仍可能显示渠道未启用，但通过 v2.product.get_item_base_info 查询时，渠道状态已正确更新。
为避免开发者基于缓存数据进行业务判断，平台计划逐步下线 v2.product.update_item 接口 response 中的 logistics 相关字段。
调整内容
自 2026/06/15 起：
v2.product.update_item response 中将不再返回 logistics 相关字段
update_item request 中的 logistics 参数仍保持支持
接口仍会正常处理物流渠道更新逻辑
如需获取最新物流信息，请调用v2.product.get_item_base_info。
平台正在评估进一步优化 update_item 接口返回结构，相关安排将另行公告通知。
生效时间：
2026.06.15
§9 4. 新增部分取消订单能力
为帮助卖家在部分商品缺货时继续履约订单，Shopee Open API 将支持部分取消订单。更新后，符合条件的卖家可仅取消订单中的缺货商品，并继续发货其余商品。
该功能将优先在 TH 逐步开放。
具体更新如下：
- v2.order.get_order_detail 和 v2.order.get_package_detail 接口将返回订单是否支持整单取消、部分取消，以及买家的缺货处理偏好。
| Name | Type | Description |
|---|---|---|
| can_full_cancel_order | boolean | 表示订单是否可整单取消： 如果该值为 true，卖家可以取消整笔订单； 如果该值为 false，则该订单不支持整单取消。 |
| can_partial_cancel_order | boolean | 表示订单是否符合部分取消条件。该值由系统资格校验和买家的缺货处理偏好共同决定： 如果该值为 true，卖家可以取消选定的缺货商品数量，并继续履约其余商品； 如果该值为 false，则不允许部分取消。 |
| buyer_preference_for_partial_cancellation | int64 | 表示买家对订单中缺货商品的处理偏好。可用值： 0 = 仅发货可用商品（买家允许卖家取消不可用商品，并继续发货其余可用商品）； 1 = 取消整笔订单（买家不允许部分取消。如有任何商品缺货，卖家应取消整笔订单）。 |
- 为了帮助卖家准确区分商品数量状态并识别每件商品的可取消数量，v2.order.get_order_detail API 将添加以下字段。
| Name | Type | Description |
|---|---|---|
| item_list | object[] | 该对象包含本 API 调用结果的详细明细。 |
| >>active_qty | int32 | 该商品规格在订单中仍处于有效状态、且仍需履约的数量。 |
| >>cancel_requested_qty | int32 | 该商品规格当前正在取消申请中、但尚未达到最终已取消状态的数量。 |
| >>cancelled_qty | int32 | 该商品规格已经成功取消的数量。 |
| >>return_requested_qty | int32 | 该商品规格当前正在退货/退款申请中的数量。 |
| >>returned_qty | int32 | 该商品规格已经通过退货/退款流程成功退回的数量。 |
- v2.order.cancel_order 接口将支持部分取消。卖家可在请求中指定需要取消的商品及数量。
| Name | Type | Description |
|---|---|---|
| order_sn | string | Shopee 订单唯一标识。 |
| cancel_reason | string | 卖家想要取消该订单的原因。 |
| partial_cancel_item_list | object[] | 卖家想要部分取消的商品规格及数量列表。当卖家因部分商品不可用而仅希望取消订单中的一部分、并继续履约其余商品时，应提供该字段。 |
| >>item_id | int64 | 需要部分取消的商品唯一标识。 |
| >>model_id | int64 | 需要部分取消的商品规格唯一标识。 |
| >>order_item_id | int64 | 订单商品标识。对于同一捆绑促销中的商品，order_item_id 应共用相同 ID，例如 1、2。对于非捆绑促销商品，order_item_id 应与 item_id 相同。 |
| >>promotion_group_id | int64 | 商品促销标识。加购优惠和捆绑促销商品必填。对于同一加购优惠或捆绑促销中的商品，promotion_group_id 应共用相同 ID。对于非加购优惠或捆绑促销商品，promotion_group_id 应为 0。该数据来自 v2.order.get_order_detail 的 promotion_group_id。 |
| >>model_quantity | int64 | 需要取消的指定商品规格数量。 |
Note：如果 v2.order.get_order_detail 返回 can_partial_cancel_order 为 false，则调用将失败。
- Shopee 将新增接口 v2.order.get_estimiate_cancel_value，支持卖家在提交部分取消请求前查询预计取消金额。
请求参数：
| Name | Type | Description |
|---|---|---|
| order_sn | string | Shopee 订单唯一标识。 |
| partial_cancel_item_list | object[] | 卖家在提交实际部分取消请求前，希望用于预估取消金额的商品规格及数量列表。 |
| >>item_id | int64 | 需要纳入预计取消金额计算的商品唯一标识。 |
| >>model_id | int64 | 需要纳入预计取消金额计算的商品规格唯一标识。 |
| >>order_item_id | int64 | 订单商品标识。对于同一捆绑促销中的商品，order_item_id 应共用相同 ID，例如 1、2。对于非捆绑促销商品，order_item_id 应与 item_id 相同。 |
| >>promotion_group_id | int64 | 商品促销标识。加购优惠和捆绑促销商品必填。对于同一加购优惠或捆绑促销中的商品，promotion_group_id 应共用相同 ID。对于非加购优惠或捆绑促销商品，promotion_group_id 应为 0。该数据来自 v2.order.get_order_detail 的 promotion_group_id。 |
| >>model_quantity | int64 | 需要纳入预计取消金额计算的指定商品规格数量。 |
返回参数：
| Name | Type | Description |
|---|---|---|
| cancel_value | int64 | 所选商品数量的预计取消金额。该值在实际提交取消前计算，可用于帮助卖家预览预计取消金额并确认部分取消。 |
Related APIs：
v2.order.get_order_detail
v2.order.get_package_detail
v2.order.cancel_order
v2.order.get_estimate_cancel_value
Effective Date on Live：
2026.05.22