来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of Payment, Order, Return, Logistics, and 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. Order and Payment APIs: Add `line_item_id` Field
1. Order and Payment APIs: Add line_item_id Field
In some scenarios, such as Bundle Deal orders, multiple item lines may have the same order_item_id, making it difficult for sellers to accurately match item details across v2.order.get_order_detail, v2.payment.get_escrow_detail and v2.payment.get_escrow_detail_batch.
To help sellers more accurately identify and match item lines in an order, Shopee Open API will add the line_item_id field to these three APIs. After this update, sellers can use line_item_id to distinguish different item lines within an order.
The detailed update is as follows:
| Field Name | Type | Description |
|---|---|---|
| line_item_id | string | Item line ID, used to distinguish different item lines within an order. |
Affected APIs:
v2.order.get_order_detail
v2.payment.get_escrow_detail
v2.payment.get_escrow_detail_batch
Effective Date:
Lived
§3 2. Seller Compensation Amount Details Added to Return Detail API
2. Seller Compensation Amount Details Added to Return Detail API
To help sellers better understand the composition of compensation amounts in return/refund scenarios, Shopee Open API will add seller compensation amount detail fields to v2.returns.get_return_detail.
After this update, sellers can view different types of return-related compensation amounts through the API, such as logistics-related compensation and shipping fee claim compensation, making it easier to verify compensation information in return/refund requests.
Note: This feature is currently in a phased rollout, and sellers not on the whitelist cannot use it. It is expected to be fully implemented by early August.
The detailed update is as follows:
| Field Name | Type | Description |
|---|---|---|
| compensation_amount_list | object[] | List of seller compensation amount details. |
| >>compensation_type | string | Compensation type. |
| >>compensation_amount | float | Compensation amount for the corresponding compensation type. |
Field description:
compensation_type indicates the type of return-related compensation. Possible values include:
| Value | Description |
|---|---|
| LOGISTICS_RELATED_COMPENSATION | Logistics-related compensation. |
| SHIPPING_FEE_CLAIM | Shipping fee claim compensation. |
| RETURN_REFUND_COMPENSATION | Return/refund-related compensation. |
| GRACE_PERIOD_COMPENSATION | Grace period-related compensation. |
| GRACE_PERIOD_LOGISTICS_COMPENSATION | Grace period logistics-related compensation. |
| LOST_DAMAGE_CLAIM_COMPENSATION | Lost or damaged parcel claim compensation. |
Response example:
Affected API:
v2.returns.get_return_detail
Effective Date:
July 16, 2026
§4 3. High Value AWB Tag Update for SPX Special Order Handling
3. High Value AWB Tag Update for SPX Special Order Handling
To help sellers retrieve more SPX special order handling information when generating AWBs through Open API, Shopee will add new AWB tag information to the related shipping document APIs. This update helps sellers identify order characteristics such as high-value items, dangerous goods type, hotspot area, driver zone, and weekend delivery success rate, so that parcels can be handled more effectively during fulfillment.
The update details are as follows:
- v2.logistics.get_shipping_document_data_info adds the following response parameters
| Name | Type | Description | Applicable Markets |
|---|---|---|---|
| high_value | boolean | Indicates whether the order is a high-value item order. Applicable values: true means the order contains a high-value item; false means the order does not contain a high-value item. | MY, TH |
| dg_specific_type | int | Indicates the dangerous goods type of the Booking order. Applicable values: 0 = Not classified / no DG sub-type, 1 = DG_A, 2 = DG_B, 3 = DG_C, 4 = DG_D. | BR, ID, VN, PH |
| hotspot_id | string | Indicates the hotspot area ID of the order. A hotspot area usually refers to a high-density last-mile delivery area. This field helps identify whether the parcel belongs to a hotspot area and supports parcel routing and delivery arrangement. | LA, MY, TH |
| weekend1_delivery_success_label | string | Indicates the delivery success rate level of the order for the first weekend date. Applicable values: H = High, M = Medium, L = Low. | MY |
| weekend2_delivery_success_label | string | Indicates the delivery success rate level of the order for the second weekend date. Applicable values: H = High, M = Medium, L = Low. | MY |
Notes:
- The new fields above only apply to SPX channels and will only return applicable values for the corresponding applicable markets and applicable order scenarios. The fields will return empty for non-applicable markets.
- AWBs for booking orders and preprinted AWBs generated before shipment are not supported for the new tag information in this update.
- For MY orders, the applicable values returned for dg_specific_type are DG, Non-DG, or Prohibited. DG_A to DG_D only apply when the seller has declared the DG type at listing level.
- v2.logistics.get_booking_shipping_document_data_info adds the following response parameter
| Name | Type | Description | Applicable Markets |
|---|---|---|---|
| dg_specific_type | int | Indicates the dangerous goods type of the Booking order. Applicable values: 0 = Not classified / no DG sub-type, 1 = DG_A, 2 = DG_B, 3 = DG_C, 4 = DG_D. | BR, ID, VN, PH |
Developers are advised to update their self-designed AWB templates or related handling logic based on the new fields and AWB display information, so that SPX special order handling tags can be displayed correctly.
Related APIs
v2.logistics.get_shipping_document_data_info
v2.logistics.download_shipping_document
v2.logistics.download_shipping_document_job
v2.logistics.download_to_label
v2.logistics.get_booking_shipping_document_data_info
v2.logistics.download_booking_shipping_document
Effective Date on Live
July 17, 2026
§5 4. Instant Mart: New Item Mapping Query API and Publishing Logic Update
4. Instant Mart: New Item Mapping Query API and Publishing Logic Update
Background
Instant Mart currently includes two types of store structures: Outlet For Instant Delivery and Warehouse-Outlet.
To support the Instant Mart business model, the platform has added a product mapping query API and optimized the product publishing logic to help developers more accurately query the mapping relationship between Outlet Shop products and Mart Shop products, while also adapting to the inventory management method of Warehouse Outlet Shop.
Note: Currently, the Warehouse-Outlet type only exists in the ID region.
Applicable Scope
Instant Mart merchants
Update Details
This API allows developers to retrieve the corresponding Mart Shop item information using an Outlet Shop item ID.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| outlet_item_id | int64 | Yes | The item ID of the item in the Outlet Shop |
Response Parameters
The response structure is the same as v2.product.get_mart_item_mapping_by_id.
For details, please refer to the API documentation:
v2.product.get_mart_item_by_outlet_item_id.
- Update to v2.product.publish_item_to_outlet_shop
When products are published to the Warehouse Outlet Shop, inventory data will be managed according to Instant Mart business logic.
Affected APIs
v2.product.get_mart_item_by_outlet_item_id
v2.product.publish_item_to_outlet_shop
Effective Date
Lived
尊敬的开发者
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验,并为集成提供更好的支持。
§6 1. Order 和 Payment API 新增 line_item_id 字段
1. Order 和 Payment API 新增 line_item_id 字段
在部分场景下,例如 Bundle Deal 订单,多个商品行可能存在相同的 order_item_id, 导致卖家难以将 v2.order.get_order_detail, v2.payment.get_escrow_detail 和 v2.payment.get_escrow_detail_batch 中的明细进行准确匹配。更新后,卖家可使用 line_item_id 区分订单中的不同商品行。
为帮助卖家更准确地识别和匹配订单中的商品行, Shopee Open API 将在这三个接口中新增line_item_id 字段。
具体更新如下:
| Field Name | Type | Description |
|---|---|---|
line_item_id | string | 商品行 ID, 用于区分订单中的不同商品行。 |
影响 API:
v2.order.get_order_detail
v2.payment.get_escrow_detail
v2.payment.get_escrow_detail_batch
上线时间:
已上线
§7 2. Return Detail API 新增卖家补偿金额明细
2. Return Detail API 新增卖家补偿金额明细
为帮助卖家更清晰地了解退货退款场景下的补偿金额构成, Shopee Open API 将在 v2.returns.get_return_detail 接口中新增卖家补偿金额明细字段。
更新后,卖家可通过接口查看不同类型的退货相关补偿金额,例如物流相关补偿、运费索赔补偿等,从而更好地核对退货退款请求中的补偿信息。
Note: 该功能目前正在灰度中,没在白名单内的卖家无法使用该功能,预计八月初全部生效。
具体更新如下:
v2.returns.get_return_detail 接口将新增以下 Response 字段:
| Field Name | Type | Description | |
|---|---|---|---|
| compensation_amount_list | |||
| >>compensation_type | string | 补偿类型。 | |
| >>compensation_amount | float | 对应补偿类型的补偿金额。 |
字段说明:
compensation_type 用于表示退货相关补偿类型。可能返回的补偿类型包括:
| Value | Description |
|---|---|
| LOGISTICS_RELATED_COMPENSATION | 物流相关补偿。 |
| SHIPPING_FEE_CLAIM | 运费索赔补偿。 |
| RETURN_REFUND_COMPENSATION | 退货退款相关补偿。 |
| GRACE_PERIOD_COMPENSATION | 宽限期相关补偿。 |
| GRACE_PERIOD_LOGISTICS_COMPENSATION | 宽限期物流相关补偿。 |
| LOST_DAMAGE_CLAIM_COMPENSATION | 丢失或损坏索赔补偿。 |
返回示例:
影响 API:
v2.returns.get_return_detail
上线时间:
2026年 7月 16日
§8 3.SPX 特殊订单处理高价值 AWB标签更新
3.SPX 特殊订单处理高价值 AWB标签更新
为帮助卖家通过 Open API 生成面单时获取更多 SPX 特殊订单处理信息, Shopee 将在面单相关的API 中新增部分面单标签信息。可帮助卖家识别高价值商品、危险品类型、热点区域、司机区域以及周末派送成功率等订单特征,从而更好地处理包裹履约。
具体更新内容如下:
- v2.logistics.get_shipping_document_data_info 新增响应以下参数
| Name | Type | 描述 | 适用市场 |
|---|---|---|---|
| high_value | boolean | 标识该订单是否为高价值商品订单 适用值: true 表示该订单包含高价值商品 false表示订单不包含高价值商品 | MY, TH |
| dg_specific_type | int | 标识订单的危险品类型。适用值: 0 = Not classified / no DG sub-type, 1 = DG_A, 2 = DG_B, 3 = DG_C, 4 = DG_D | BR, ID, PH, VN |
| hotspot_id | string | 标识订单对应的热点区域 ID 热点区域通常指末端派送密度较高的区域,该字段可帮助识别包裹是否属于热点区域,并用于包裹路由及派送安排 | LA, MY, TH |
| weekend1_delivery_success_label | string | 标识订单在第一个周末日期的派送成功率等级 适用值: H = High, M = Medium, L = Low | MY |
| weekend2_delivery_success_label | string | 标识订单在第二个周末日期的派送成功率等级 适用值: H = High, M = Medium, L = Low | MY |
注意:
- 以上新增字段仅适用于 SPX 渠道,并仅在对应适用市场及适用订单场景下返回适用值,非适用市场将返回空
- 预先履约订单的面单,以及发货前预打印的面单,暂不支持本次新增的标签信息。
- 对于MY的订单, dg_specific_type 返回的适用值有 DG、Non-DG 或 Prohibited ;DG_A 至 DG_D 仅在卖家已在商品层级申报 DG 类型时适用。
- v2.logistics.get_booking_shipping_document_data_info 新增响应以下参数
| Name | Type | 描述 | 适用市场 |
|---|---|---|---|
| dg_specific_type | int | 标识订单的危险品类型。适用值:0 = Not classified / no DG sub-type, 1 = DG_A, 2 = DG_B, 3 = DG_C, 4 = DG_D | BR, ID, VN |
建议开发者根据新增字段及 AWB 展示信息,更新自画AWB 模板或相关处理逻辑,以确保 SPX 特殊订单处理标签能够正确展示。
影响接口
v2.logistics.get_shipping_document_data_info
v2.logistics.download_shipping_document
v2.logistics.download_shipping_document_job
v2.logistics.download_to_label
v2.logistics.get_booking_shipping_document_data_info
v2.logistics.download_booking_shipping_document
上线时间
2026年7月17日
§9 4. Instant Mart新增商品映射查询接口及发布逻辑调整
4. Instant Mart新增商品映射查询接口及发布逻辑调整
背景
Instant Mart 目前包含两种店铺结构: Outlet For Instant Delivery 和 Warehouse-Outlet。
为支持 Instant Mart 业务模式,平台新增商品映射查询接口,并优化商品发布逻辑,帮助开发者更准确地查询 Outlet Shop 商品与 Mart Shop 商品之间的映射关系,同时适配 Warehouse Outlet Shop 的库存管理方式。
Note:当前Warehouse-Outlet类型只存在于ID region。
影响范围
Instant Mart 商家
更新内容
支持通过 Outlet Shop 商品 ID 查询对应的 Mart Shop 商品信息。
Request Parameters
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| outlet_item_id | int64 | Yes | The item ID of the item in the outlet shop. |
Response Parameters
返回结构与v2.product.get_mart_item_mapping_by_id 保持一致,详见API文档: v2.product.get_mart_item_by_outlet_item_id
当商品发布至 Warehouse Outlet Shop 时, 库存数据将按照 Instant Mart 业务逻辑进行管理。
影响接口
v2.product.get_mart_item_by_outlet_item_id
v2.product.publish_item_to_outlet_shop
生效时间
Lived