Significant OpenAPI Updates of Returns, SBS and Product

stable本次发布有变化全部展示

来自 Shopee 官方资料快照 · 2026-09-07 04:45:17

打开官方原文 ↗

当前资料结构化阅读页
固定快照已留存，可追溯
官方原文可核对

查看技术与溯源信息

平台 / profile: Shopee / profile.shopee.announcements
语言: en
发布版本: cn-20260909-2
标签: zhuge/sourceplatform/shopeeaudience/developercategory/announcementtopic/apitopic/api-producttopic/api-returnstopic/api-sbstopic/changelogtopic/developertopic/openapi-updates

资料正文

§1 Significant OpenAPI Updates of Returns, SBS 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. Return List and Return Detail APIs Add Partial Return and Refund Amount Adjustment Fields

1. Return List and Return Detail APIs Add Partial Return and Refund Amount Adjustment Fields

To help large sellers and ISV providers more accurately identify and filter return/refund requests, Shopee Open API will add fields related to partial returns and refund amount adjustments to the Return List and Return Detail APIs.

After this update, sellers can use the APIs to identify the following scenarios:

The buyer returns only part of the item quantity. For example, the buyer purchased three units but requests to return only one unit.
The actual refund amount is lower than the maximum refundable amount for the return/refund request. For example, the maximum refundable amount is USD 200, but the buyer requests a refund of only USD 100.

The details are as follows:

The v2.returns.get_return_list and v2.returns.get_return_detail APIs will add the following response fields:

Field Name	Type	Description
is_partial_quantity_return	boolean	Indicates whether the return request includes items with partial quantities returned. true indicates that the return request includes a partial quantity return.
is_refund_amount_adjusted	boolean	Indicates whether the actual refund amount is lower than the maximum refundable amount. true indicates that the actual refund amount is lower than the maximum refundable amount.

Sellers can use these fields to filter return/refund requests and manage partial quantity returns and refund amount adjustments according to their business processes.

Affected APIs

v2.returns.get_return_list
v2.returns.get_return_detail

Effective Date

August 17, 2026

§3 2. Product APIs Adjust Condition Field Validation and Response Logic

2. Product APIs Adjust Condition Field Validation and Response Logic

Background

To reduce compliance risks caused by used items being misclassified as new, Shopee will adjust the Condition field logic for BR listings.

After this update, sellers must explicitly select an item Condition when creating or editing a listing. The system will no longer allow items to be published or saved without a valid Condition value. OpenAPI will also adjust the related write and read endpoints to ensure that the Condition field serves as the accurate source of truth for item condition.

Applicable Scope

Update Details

The following Product OpenAPIs will adjust the validation and response logic related to the Condition field.

API	Field	Type	Description
v2.product.add_item	condition	Validation Change	When creating an item, a valid Condition value must be provided. If the field is missing, empty, or null, the request will be rejected. If the submitted value is not in the allowed list, the request will also be rejected.
v2.product.update_item	condition	Validation Change	When updating an item, a valid Condition value must be provided. If the field is missing, empty, or null, the request will be rejected. If the submitted value is not in the allowed list, the request will also be rejected.
v2.global_product.add_global_item	condition	Validation Change	For global items, a valid condition value must be provided when creating an item. If the field is missing, empty, or null, the request will be rejected.
v2.product.get_item_base_info	condition	Response Logic Change	When querying item base information, the API will return the correct Condition value based on the Condition section.

Note:

For BR local items and CB items, condition will become a mandatory field. For items in other regions, the existing logic remains unchanged: condition can be omitted when creating an item, and if omitted, it will default to New.

The condition field only supports NEW or USED, case-insensitive. Therefore, USED, Used, and used will be mapped to Used; NEW, New, and new will be mapped to New. Other values will be rejected with the following error message: Invalid condition value. Please provide a valid item condition.

When condition is missing, empty, or null during the creation of a BR local item or CB item, the API will return the following error message: Item condition is required. Please provide a valid item condition.

Related APIs

v2.product.add_item

v2.global_product.add_global_item

v2.product.update_item

v2.product.get_item_base_info

Effective Date

August 17, 2026

§4 3. SBS Adds Fulfillment Mapping Inventory Query API

3. SBS Adds Fulfillment Mapping Inventory Query API

Background

To improve Parent SKU inventory visibility and support sellers' ERP systems in obtaining Fulfillment Mapping relationships and inventory information, Shopee will add a new SBS OpenAPI.

This API allows sellers to query the corresponding Fulfillment Mapping and inventory information using the MTSKU ID of either a Bundle SKU or a Parent SKU. It helps developers support automated inventory reconciliation and planning, reduce manual operations, and mitigate cross-channel overselling risks.

Applicable Scope

Sellers using Fulfillment Mapping

Update Details

A new API, v2.sbs.get_fulfillment_mapping_inventory_list, will be added to query Fulfillment Mapping relationships and inventory information.

Request Parameters

Field	Field Type	Description
mtsku_ids	string	The MTSKU ID of either a Bundle SKU or a Parent SKU. Up to 100 comma-separated MTSKU IDs can be queried in one request, and all MTSKU IDs must belong to the specified shop_id.
page_size	int32	The number of records returned in each query. The value range is 1-100. If not provided, the default value is 100.
next_cursor	string	The cursor for the next page query. It can be omitted for the first query. If a non-empty next_cursor is returned in the response, it can be used to continue retrieving the next page of data.

Response Parameters

Field	Field Type	Description
list > bundle_mtsku_id	string	Bundle SKU.
list > mapping_type	int64	Fulfillment Mapping type. Enum values: 1-group; 2-lucky bag; 3-mapping list.
list > mapping_formula	string	The Fulfillment Mapping formula of the Bundle MTSKU. It describes the Parent MTSKU composition or alternative mapping relationships.
list > whs_id	string	Shopee warehouse ID.
list > stock_context > physical_sellable_stock	int64	The physical sellable stock for the Bundle MTSKU, excluding any mapping converted stock.
list > stock_context > parent_mtsku_list > parent_mtsku_id	string	The MTSKU ID of a Parent SKU involved in the Fulfillment Mapping relationship.
list > stock_context > parent_mtsku_list > parent_mtsku_stock	int64	The physical sellable stock of the Parent MTSKU in the specified warehouse. It is the original quantity and is not multiplied by the mapping_formula.
list > stock_context > mapping_sellable_stock	int64	The calculated mapping sellable stock converted from Parent MTSKUS.
total	int64	The total number of records that meet the query conditions.
next_cursor	string	The cursor for the next page. If a non-empty string is returned, it indicates that more data is available for retrieval.

Note:

When mtsku_ids is not provided, the API returns all Fulfillment Mapping records with available Bundle SKU stock for the shop.

When mtsku_ids is provided, the API returns all matching Fulfillment Mapping records for the specified Bundle SKU or Parent SKU. If an MTSKU participates in multiple Fulfillment Mapping relationships, all matching relationships will be returned in list, with pagination supported through page_size and next_cursor.

Effective Date

2026-08-12

尊敬的开发者

请查收本次的 OpenAPI 功能更新。这些改动旨在提升功能灵活性、优化使用体验,并为集成提供更好的支持。

§5 1. 退货列表及退货详情 API 新增部分退货与退款金额调整字段

1. 退货列表及退货详情 API 新增部分退货与退款金额调整字段

为帮助大型卖家及 ISV 服务商更准确地识别和筛选退货退款请求, Shopee Open API 将在退货列表及退货详情接口中新增部分退货和退款金额调整相关字段。

更新后,卖家可通过 API 识别以下场景:

买家仅退回商品的部分数量。例如,订单中购买了 3 件商品,但买家仅申请退回其中1件。
实际退款金额低于该退货退款请求对应的最高可退款金额。例如,最高可退款金额为 200 美元,但买家实际申请退款 100 美元。

具体更新如下:

v2.returns.get_return_list 和 v2.returns.get_return_detail 接口将新增以下 Response 字段:

Field Name	Type	Description
is_partial_quantity_return	boolean	表示该退货请求是否包含部分数量退货的商品。true 表示该退货请求包含部分数量退货。
is_refund_amount_adjusted	boolean	表示实际退款金额是否低于最高可退款金额。true 表示实际退款金额低于最高可退款金额。

卖家可基于上述字段对退货退款请求进行筛选,并结合自身业务流程处理部分数量退货及退款金额调整场景。

影响 API:

v2.returns.get_return_list

v2.returns.get_return_detail

上线时间:

2026年08月17日

§6 2. Product 接口调整 Condition 字段校验及返回逻辑

2. Product 接口调整 Condition 字段校验及返回逻辑

背景

为降低二手商品被误分类为全新商品所带来的合规风险, Shopee 将调整 BR 站点商品 Condition 字段逻辑。

更新后,卖家在创建或编辑商品时必须明确选择商品 Condition,系统将不再允许在缺少有效 Condition 值的情况下发布或保存商品。OpenAPI 将同步调整相关写入及查询接口,确保 Condition 字段作为商品状态的准确来源。

适用范围

更新内容

以下 Product OpenAPI 将调整 Condition 字段相关校验及返回逻辑。

API	Field	Type	Description
v2.product.add_item	condition	Validation Change	创建商品时,必须传入有效的 Condition 值。若未传入、为空或为 null,接口将拒绝请求。若传入值不在允许范围内,接口也将拒绝请求。
v2.product.update_item	condition	Validation Change	更新商品时,必须传入有效的 Condition 值。若未传入、为空或为 null,接口将拒绝请求。若传入值不在允许范围内,接口也将拒绝请求。
v2.global_product.add_global_item	condition	Validation Change	对于 global item,创建商品时必须传入有效的 condition 值。若未传入、为空或为 null,接口将拒绝请求。
v2.product.get_item_base_info	condition	Response Logic Change	查询商品基础信息时,接口将基于 Condition section 返回正确的 Condition 值。

Note:

对于 BR 本地商品及 CB 商品, condition 将变为必填字段。其他地区商品仍保持现有逻辑:创建商品时可不传入 condition,未传入时默认处理为 New。

condition 字段仅支持 NEW 或 USED,不区分大小写。因此,USED、Used、used 将映射为 Used; NEW、New、new 将映射为 New。其他值将被拒绝,并返回错误信息:Invalid condition value. Please provide a valid item condition.

当 BR 本地商品或 CB 商品创建时 condition 缺失、为空或为 null,接口将返回错误信息:Item condition is required. Please provide a valid item condition.

§7 3. SBS 新增 Fulfillment Mapping 库存查询接口

3. SBS 新增 Fulfillment Mapping 库存查询接口

背景

为提升 Parent SKU 库存透明度,并支持卖家 ERP 系统获取 Fulfillment Mapping 关系及库存信息, Shopee 将新增 SBS OpenAPI。

该接口支持卖家通过 Bundle SKU 或 Parent SKU 的 MTSKU ID 查询对应的 Fulfillment Mapping 及库存信息,帮助开发者进行自动化库存对账与库存规划,降低人工操作成本及跨渠道超卖风险。

适用范围

使用 Fulfillment Mapping 的卖家

更新内容

新增接口v2.sbs.get_fulfillment_mapping_inventory_list, 用于查询 Fulfillment Mapping 关系及库存信息。

Request Parameters

Field	Field Type	Description
mtsku_ids	string	Bundle SKU 或 Parent SKU 的 MTSKU ID。单次请求最多支持查询 100 个以英文逗号分隔的 MTSKU ID, 且所有 MTSKU ID 必须属于指定 shop_id。
page_size	int32	每次查询返回的记录数,取值范围为 1-100。未传入时默认返回 100 条。
next_cursor	string	下一页查询 cursor。首次查询可不传;如 response 返回非空 next_cursor,可用于继续查询下一页数据。

Response Parameters

Field	Field Type	Description
list > bundle_mtsku_id	string	Bundle SKU 的 MTSKU ID。
list > mapping_type	int64	Fulfillment Mapping 类型。枚举值:1-group; 2-lucky bag; 3-mapping list.
list > mapping_formula	string	Bundle MTSKU 的 Fulfillment Mapping 公式,用于描述 Parent MTSKU 的组成��替代映射关系。
list > whs_id	string	Shopee warehouse ID。
list > stock_context > physical_sellable_stock	int64	Bundle MTSKU 的 physical sellable stock,不包含 mapping 转换库存。
list > stock_context > parent_mtsku_list > parent_mtsku_id	string	Fulfillment Mapping 关系中 Parent SKU 的 MTSKU ID。
list > stock_context > parent_mtsku_list > parent_mtsku_stock	int64	指定仓库下 Parent MTSKU 的 physical sellable stock,返回原始库存数量,不会按 mapping_formula 倍数放大。
list > stock_context > mapping_sellable_stock	int64	根据 Parent MTSKU 库存计算得出的 mapping sellable stock。
total	int64	符合查询条件的数据总量。
next_cursor	string	下一页 cursor。若返回非空字符串,表示仍有更多数据可继续查询。

Note:

当 mtsku_ids 未传入时,接口将返回该店铺下所有有可售 Bundle SKU 库存的 Fulfillment Mapping 记录。

当 mtsku_ids 已传入时,接口将返回指定 Bundle SKU 或 Parent SKU 命中的 Fulfillment Mapping 记录。若某个 MTSKU 同时参与多个 Fulfillment Mapping 关系,接口会在 response list 中返回所有匹配关系,并通过 page_size 和 next_cursor 分页返回。