来自 Shopee 官方资料快照 ·
- 当前资料结构化阅读页
- 固定快照已留存，可追溯
- 官方原文可核对
资料正文
§1 Significant OpenAPI Updates of 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. Add Product Promotion Information Fields to Escrow Detail API
1. Add Product Promotion Information Fields to Escrow Detail API
To help developers clearly identify product-level promotions for easier reconciliation and sales analysis, we have added a new parameter promotion_list under the items field in the response of the v2.payment.get_escrow_detail and v2.payment.get_escrow_detail_batch APIs.
The promotion_list parameter returns all promotions that the product participates in, including the promotion type and promotion ID.
Example:
"promotion_list": [
{
"promotion_id": 754274883912704,
"promotion_type": "seller_discount"
}
]
For compatibility purposes, the existing fields activity_type and activity_id under items filed will remain temporarily.Their deprecation schedule will be announced later.
Affected APIs
v2.payment.get_escrow_detail
v2.payment.get_escrow_detail_batch
Effective Date
2025.10.14
§3 2. [Only for TW] v2.order.split_order restrictions for installment payment orders
2. [Only for TW] v2.order.split_order restrictions for installment payment orders
To comply with bank and credit card agreements, Shopee Taiwan (TW) is updating the order split functionality. Orders meeting any of the following conditions cannot be split to prevent refund failures and ensure a smooth user experience:
- Payment Method is Credit Card Installment
- Payment Method is SpayLater with Installment Plan greater than 1x
When calling the v2.order.split_order, if the order meets the above conditions, the API will return the following error and prevent the order from being split:
{
"error": "order.order_cannot_split",
"message": "Cannot split order paid by Credit Card Installment payment method or SPayLater payment method with installment plan greater than 1x."
}
Please update your system logic accordingly to ensure API calls comply with the new split restriction.
Affected APIs
v2.order.split_order
Effective Date
2025.10.14
§4 3. [Only for BR] v2.order.get_order_detail adds payment_info.payment_amount field
3. [Only for BR] v2.order.get_order_detail adds payment_info.payment_amount field
To support splitting amounts for orders paid with multiple payment methods, the payment_info object in v2.order.get_order_detail has added a new field: payment_amount.
The updated payment_info structure is as follows:
| Name | Type | Sample | Description |
|---|---|---|---|
| payment_info | object[] | / | List of payment information. |
| >>payment_method | string | Debit Card | Payment method used in the order. |
| >>payment_processor_register | string | 38.372.267/0001-82 | CNPJ of the payment processor handling the transaction. |
| >>card_brand | string | VISA | Card brand for credit or debit transactions. Empty for Pix payments. |
| >>transaction_id | string | 951679 | Payment authorization code generated by the bank or payment processor to validate the transaction. |
| >>payment_amount | float | 150.75 | Payment amount for this payment method. |
Sample Response:
{
"payment_info":[
{
"payment_method":"Debit Card",
"payment_processor_register":"38.372.267/0001-82",
"card_brand":"VISA",
"transaction_id":"951679",
"payment_amount":150.75
},
{
"payment_method":"Pix",
"payment_processor_register":"38.372.267/0001-82",
"card_brand":"",
"transaction_id":"1000401300000146826",
"payment_amount":50.25
}
]
}
Please update your systems accordingly to ensure that payment amounts are accurately reflected in XML invoices.
For details on the previous update introducing the payment_info structure and related fields, please refer to the announcement: [IMPORTANT] New SEFAZ NT 2025.001 Payment Parameters Required in XML.
Affected APIs
v2.order.get_order_detail
Effective Date
2025.10.24
尊敬的开发者
请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验，并为集成提供更好的支持。
§5 1. 新增商品活动信息字段至 Escrow Detail 接口
1. 新增商品活动信息字段至 Escrow Detail 接口
为了使开发者更清晰地识别商品参与的促销活动，有助于进行结算对账与销售分析，我们在v2.payment.get_escrow_detail 和v2.payment.get_escrow_detail_batch的响应体中 items 字段下新增了参数 promotion_list，用于返回该商品参与的所有活动及对应活动ID及对应的活动类型。
示例：
"promotion_list": [
{
"promotion_id": 754274883912704,
"promotion_type": "seller_discount"
}
]
为保证兼容性，items 下的原有字段 activity_type 与 activity_id 将 暂时保留，下线时间将另行通知。
影响接口
v2.payment.get_escrow_detail
v2.payment.get_escrow_detail_batch
生效日期
2025.10.14
§6 2.【仅适用于台湾】v2.order.split_order 接口新增分期付款订单拆分限制
2.【仅适用于台湾】v2.order.split_order 接口新增分期付款订单拆分限制
为遵守银行及信用卡合约规定，Shopee 台湾站点 (TW) 对订单拆分功能进行了调整。满足以下任一条件的订单将不允许拆单，以避免退款失败影响用户体验：
- Payment Method 为 Credit Card Installment
- Payment Method 为 SpayLater 且 Installment Plan 大于 1x
调用 v2.order.split_order 时，若订单符合上述条件，接口将返回以下错误信息并阻止拆单：
{
"error": "order.order_cannot_split",
"message": "Cannot split order paid by Credit Card Installment payment method or SPayLater payment method with installment plan greater than 1x."
}
请根据更新内容及时调整系统逻辑，确保接口调用符合新的拆分限制。
影响接口
v2.order.split_order
生效日期
2025.10.14
§7 3.【仅适用于巴西】v2.order.get_order_detail 新增 payment_info.payment_amount 字段
3.【仅适用于巴西】v2.order.get_order_detail 新增 payment_info.payment_amount 字段
为了支持多种支付方式合并支付订单下的金额拆分，v2.order.get_order_detail 的 payment_info 字段下新增了 payment_amount 字段。
更新后的 payment_info 结构如下：
| Name | Type | Sample | Description |
|---|---|---|---|
| payment_info | object[] | / | 支付信息列表 |
| >>payment_method | string | Debit Card | 订单使用的支付方式 |
| >>payment_processor_register | string | 38.372.267/0001-82 | 处理支付交易的收单机构 CNPJ |
| >>card_brand | string | VISA | 信用卡或借记卡的品牌，如果是 Pix 支付，则为空 |
| >>transaction_id | string | 951679 | 银行或支付机构生成的支付授权码，用于验证交易有效性 |
| >>payment_amount | float | 150.75 | 对应支付方式的支付金额 |
响应示例：
{
"payment_info":[
{
"payment_method":"Debit Card",
"payment_processor_register":"38.372.267/0001-82",
"card_brand":"VISA",
"transaction_id":"951679",
"payment_amount":150.75
},
{
"payment_method":"Pix",
"payment_processor_register":"38.372.267/0001-82",
"card_brand":"",
"transaction_id":"1000401300000146826",
"payment_amount":50.25
}
]
}
请根据更新内容及时调整系统逻辑，确保支付金额信息在 XML 开票中正确显示。
关于此前发布的 payment_info 结构及相关字段的更新详情，请参阅公告：[IMPORTANT] New SEFAZ NT 2025.001 Payment Parameters Required in XML。
影响接口
v2.order.get_order_detail
生效日期
2025.10.24