来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of Product, Return, Payment, and 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. OpenAPI Adds uint64 Field Type
1. OpenAPI Adds uint64 Field Type
Background
To support the numeric range requirements of certain business fields, OpenAPI API docs will add the uint64 field type. The field types of promotion_id and activity_id in some APIs will be adjusted to uint64.
Applicable Scope
Developers using related Payment, Product, and Returns APIs
Update Details
The field types of promotion_id or activity_id in the following APIs will be adjusted to uint64.
| Field | Type | Description |
|---|---|---|
| promotion_id | Field Type Change | The field type will be adjusted to uint64. |
| activity_id | Field Type Change | The field type will be adjusted to uint64. |
APIs involving the promotion_id field:
v2.payment.get_escrow_detail_batch
APIs involving the activity_id field:
v2.payment.get_escrow_detail_batch
Note:
Please adjust your API parsing and data storage logic based on the field type changes to ensure that your system can correctly handle uint64 fields and avoid parsing issues caused by field type or numeric range changes.
Related APIs
v2.payment.get_escrow_detail_batch
Effective Date
Lived
§3 2. Payment APIs Add External Party Voucher Field
2. Payment APIs Add External Party Voucher Field
Background
To support the cofund voucher business, Payment OpenAPIs will add an external party voucher amount field to help developers identify the voucher amount sponsored by external parties in an order.
Update Details
v2.payment.get_escrow_detail / v2.payment.get_escrow_detail_batch will add the following response field to display the final voucher amount provided by External Party in an order.
| Field | Type | Description |
|---|---|---|
| order_income > voucher_from_external_party | New Response Field | Final value of voucher provided by External Party for the order. Only displayed for non-CB SIP affiliate shops. |
Note:
Updated field definitions:
- voucher_from_seller: Discount Voucher amount sponsored by Seller, regardless of whether the voucher is cofund / non-cofund, or seller / Shopee voucher.
- voucher_from_shopee: Discount Voucher amount sponsored by Shopee, regardless of whether the voucher is cofund / non-cofund, or seller / Shopee voucher.
- seller_coin_cash_back: Coin Cashback cash value sponsored by Seller, regardless of whether the voucher is cofund / non-cofund, or seller / Shopee voucher.
When the value of voucher_from_external_party is 0, the APIs will still return this field with the value as 0.
Please adjust your Payment API parsing, order income calculation, and financial reconciliation logic based on the new field and the updated voucher attribution logic.
Related APIs
v2.payment.get_escrow_detail_batch
Effective Date
Live
§4 3. New Field medicine_id
3. New Field medicine_id
To meet regulatory requirements, Shopee will launch a remote consultation process for pharmaceutical-related products. Buyer must complete a consultation or consult a Pharmacist and get prescribed medicine through TelePharmacy service, and may only buy the exact prescribed medicine. To allow a listing to be recommended by the prescription, a new field called medicine_id is required for this feature. Besides that, several mandatory listing attributes has been added for medicine. Any update from OpenAPI will require all of these new fields.
Scope
ID/TH local sellers
Note: Starting August, the feature will launch gradually to limited buyers in batches. Seller access is whitelist-only and will not be opened to all sellers.
Affected Categories
When sellers create or update products under the following categories through OpenAPI, they need to provide medicine_id:
| Category ID | Category Name |
|---|---|
| 100119 | Health > Medicine & Medical Supplies > Over-the-counter Medicine |
| 102058 | Health > Medicine & Medical Supplies > Prescription |
API Update
| API | Field | Type | Description |
|---|---|---|---|
| v2.product.add_item | medicine_id | New Request Field | When creating or updating products under the specified medicine category, sellers must provide medicine_id as the unique identifier for each standardized medicine. If a medicine_id is not provided for the specified category, the API will return the error “Medicine ID is mandatory for products in Prescription/OTC category." If an incorrect medicine_id is provided, the API will return the error “Please input the correct medicine ID." |
| v2.product.update_item | medicine_id | New Request Field | Same as above |
| v2.product.get_item_base_info | medicine_id | New Response Field | If the product contains standardized medicine information, the API will return medicine_id. If the product does not contain medicine information, the field will not be returned. |
Note: medicine_id belongs to seller-side information and currently ISVs cannot obtain this value through OpenAPI. Some sellers with medicine items may be blocked from adding/editing/get info of item related to medicine items or items with medicine_id due to the partnership agreement
Therefore, the ISV system can only support manual entry of medicine_id by the seller. If the seller enters an incorrect medicine_id, OpenAPI will return the corresponding error, and the ISV system can only pass on this error message for the seller to correct and resubmit.
Affected APIs:
Effective Date on Live:
Lived
§5 4. [VN] Buyer Invoice Info API Adds national_id Field
4. [VN] Buyer Invoice Info API Adds national_id Field
To help sellers in Vietnam generate legally compliant VAT invoices more efficiently, Shopee Open API will add buyer National ID information to the v2.order.get_buyer_invoice_info API.
After this update, when a buyer submits personal invoice information, sellers can obtain the national_id field through Open API for personal invoice issuance.
The detailed update is as follows:
The invoice_detail object in v2.order.get_buyer_invoice_info will add the following response field:
| Field Name | Type | Description |
|---|---|---|
| national_id | string | Buyer's National ID. This field only applies to VN site invoice information where invoice_type is personal. It may be masked depending on the order status and platform permission rules. |
Affected API:
v2.order.get_buyer_invoice_info
Effective Date:
July 28, 2026
尊敬的开发者
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验,并为集成提供更好的支持。
§6 1. OpenAPI 字段类型新增 uint64 类型
1. OpenAPI 字段类型新增 uint64 类型
背景
为支持部分业务字段的数值范围要求, OpenAPI API doc 将新增 uint64 字段类型。部分接口中的 promotion_id 和 activity_id 字段类型将调整为 uint64。
适用范围
涉及 Payment、Product、Returns 相关接口的开发者
更新内容
以下接口中的 promotion_id 或 activity_id 字段类型将调整为 uint64。
| Field | Type | Description |
|---|---|---|
| promotion_id | Field Type Change | 字段类型调整为 uint64。 |
| activity_id | Field Type Change | 字段类型调整为 uint64。 |
promotion_id 字段涉及接口:
v2.payment.get_escrow_detail_batch
activity_id 字段涉及接口:
v2.payment.get_escrow_detail_batch
Note:
请开发者根据字段类型变更调整接口解析及数据存储逻辑,确保系统可正确处理 uint64 类型字段,避免因字段类型或数值范围导致解析异常。
相关接口
v2.payment.get_escrow_detail_batch
生效日期
Lived
§7 2. Payment 接口新增 External Party Voucher 字段
2. Payment 接口新增 External Party Voucher 字段
背景
为支持 cofund voucher 业务, Payment 相关 OpenAPI 将新增 external party voucher 金额字段, 帮助开发者识别订单中由外部方承担的 voucher 金额。
更新内容
v2.payment.get_escrow_detail/v2.payment.get_escrow_detail_batch 将新增以下 response 字段,用于展示订单中由 External Party 提供的 voucher 最终金额。
| Field | Type | Description |
|---|---|---|
| order_income > voucher_from_external_party | New Response Field | 订单中由 External Party 提供的 voucher 最终金额。仅针对 non-CB SIP affiliate shop 展示。 |
Note:
更新后字段定义:
- voucher_from_seller: 由 Seller 承担的 Discount Voucher 金额,无论该 voucher 是否为 cofund / non-cofund,或 seller / Shopee voucher。
- voucher_from_shopee: 由 Shopee 承担的 Discount Voucher 金额,无论该 voucher 是否为 cofund / non-cofund,或 seller / Shopee voucher。
- seller_coin_cash_back:由 Seller 承担的 Coin Cashback 现金价值,无论该 voucher 是否为 cofund / non-cofund, 或 seller / Shopee voucher。
当 voucher_from_external_party 字段值为 0时,接口仍会返回该字段, 字段值为0。
请开发者根据新增字段及 voucher 归属读取逻辑调整 Payment 接口解析、订单收入计算及财务对账逻辑。
相关接口
v2.payment.get_escrow_detail_batch
生效日期
Lived
§8 3. 新增药品标识字段 medicine_id
3. 新增药品标识字段 medicine_id
为满足监管要求, Shopee 将针对药品相关商品上线远程咨询流程。买家需完成咨询或通过 TelePharmacy 服务咨询药师并获取处方药品后,才可购买对应的处方药品。
为支持商品可被处方推荐,平台将新增 medicine_id 字段作为标准化药品的唯一标识。同时,药品类商品也新增了部分必填商品类目。通过 OpenAPI 创建或更新相关药品商品时, 开发者需按要求传入这些新增字段。
适用对象
ID、TH 本地卖家(仅限白名单卖家)
Note:
功能将于8月起面向买家逐步灰度小范围上线;买家侧为分批开放,卖家侧仅支持白名单准入,不会对全部卖家开放。
适用场景
当卖家通过 OpenAPI 创建或更新以下类目下的商品时,需要提供 medicine_id:
| 类目 ID | 类目名称 |
|---|---|
| 100119 | Health > Medicine & Medical Supplies > Over-the-counter Medicine |
| 102058 | Health > Medicine & Medical Supplies > Prescription |
API 更新
以下 Product 接口将新增 medicine_id 字段,用于支持药品商品创建、更新及查询。
| API | 字段 | 类型 | 说明 |
|---|---|---|---|
| v2.product.add_item | medicine_id | 新增入参字段 | 在指定药品类目下创建或更新商品日 卖家必须提供 medicine_id 作为每一款标准化药品的唯一标识。如指定类目未提供的medicine_id ,接口将报错“Medicine ID is mandatory for products in Prescription/OTC category。 如提供错误的medicine_id 接口将报错“Please input the correct medicine ID.” |
| v2.product.update_item | medicine_id | 新增入参字段 | 如上描述 |
| v2.product.get_item_base_info | medicine_id | 新增响应字段 | 若商品包含药品信息,则接口会返回 medicine_id;若商品未包含药品信息,则不会返回该字段。 |
注意:medicine_id 属于卖家侧信息,目前 ISV 无法通过 OpenAPI 获取该值。部分拥有药品商品的卖家,可能因合作协议限制,无法通过 ISV 添加、编辑或查询药品商品或含 medicine_id 的商品。
因此, ISV 系统只能支持由卖家手动填写 medicine_id。若卖家填写的 medicine_id 不正确, OpenAPI 将返回相应错误, ISV 系统也只能透传该报错信息,由卖家自行修改后重新提交。
影响接口:
上线时间:
Lived
§9 4. [VN] Buyer Invoice Info API 新增 national_id 字段
4. [VN] Buyer Invoice Info API 新增 national_id 字段
为帮助越南站点卖家更高效地生成符合法规要求的 VAT 发票, Shopee Open API 将在 v2.order.get_buyer_invoice_info 接口中新增买家 National ID 信息。
更新后,当买家提交个人发票信息时, 卖家可通过 Open API 获取 national_id 字段,用于个人类型发票开具流程。
具体更新如下:
v2.order.get_buyer_invoice_info 接口的 invoice_detail 对象中将新增以下 Response 字段:
| Field Name | Type | Description |
|---|---|---|
| national_id | string | 买家的 National ID。仅适用于 VN 站点且 invoice_type 为 personal 的发票信息。该字段可能会根据订单状态及平台权限规则进行脱敏展示。 |
影响 API:
v2.order.get_buyer_invoice_info
上线时间:
2026年7月28日