Significant OpenAPI Updates of Logistics, Returns and Product

Dear Developer,

Please note the following changes:

1. Support for retrieving cross-border tracking information for failed delivery parcels returned from local return warehouses

1.1 Business Background

For cross-border sellers, parcels with failed delivery (logistics status: LOGISTICS_DELIVERY_FAILED) due to buyer rejection or delivery failure are first returned to the local return warehouse. If parcels meet cross-border return conditions, they are then returned from the local return warehouse to the seller.

Currently, cross-border sellers cannot track the logistics status of parcels returned from the local return warehouse to the seller. To improve visibility for this logistics segment, Shopee has enhanced the v2.logistics.get_tracking_info API to return the tracking number, courier name, and tracking information for this segment.

1.2 API Updates

The v2.logistics.get_tracking_info API now includes the following fields:

Note: These fields only apply to the cross-border segment of failed delivery parcels returned from the local return warehouse to the seller.

1.3 Failed Delivery Parcel Tracking Logic (Updated Full Logic)

1. Local Failed Delivery Parcels: No cross-border transport involved. After delivery failure, parcels are returned directly to the seller using the original tracking number. Both forward logistics (seller → buyer) and full reverse logistics (buyer → local return warehouse → seller) are returned in the existing tracking_info field.

2. Cross-Border Failed Delivery Parcels:

- Forward logistics (seller → buyer) and first reverse logistics (buyer → local return warehouse): No cross-border transport involved. After delivery failure, parcels are returned to the local return warehouse using the original tracking number. This segment is returned in the existing tracking_info field.

- Last reverse logistics (local return warehouse → seller): Cross-border transport involved. A new tracking number is generated, and this segment is returned in the new reversed_tracking_number, reversed_courier_name, and reversed_tracking_info fields.

2. Support for pre-shipment printing of self-designed AWBs for certain logistics channels

2.1 Business Background

To improve seller shipping efficiency, some logistics channels support pre-shipment AWB printing, allowing sellers to prepare parcels in advance. However, the current API only supports pre-printing system-generated AWBs and does not allow sellers to obtain the data needed for self-designed AWBs via v2.logistics.get_shipping_document_data_info API before shipment.

To optimize this experience, Shopee has enhanced the v2.logistics.get_shipping_document_data_info API. For parcels that support self-designed AWBs and allow pre-shipment printing, sellers can now retrieve the necessary information before shipment and print self-designed AWBs in advance, improving shipping efficiency.

2.2 API Updates

For parcels that support self-designed AWBs and pre-shipment printing, calling the v2.logistics.get_shipping_document_data_info API before shipment will no longer return error and will instead return the following fields:

· recipient_address_info

· key

· image

· shipping_document_info

· cod

· cod_amount

· order_weight

· logistics_channel_id

· shipping_carrier

· pickup_code

3. Support for retrieving the minimum refundable amount threshold

3.1 Business Background

To improve the accuracy and efficiency of the refund process, Shopee has introduced the "minimum refundable amount" rule. This helps sellers clearly identify the lowest refundable amount when offering refunds to buyers, preventing failed refund requests due to amounts below the threshold.

3.2 API Updates

1. v2.returns.get_available_solutions API: Add new response field "min_refund_amount". It is returned when "refund_amount_adjustable" is true and indicates the minimum adjustable refund amount for the refund solution.

2. v2.returns.offer API: If the seller submits a "proposed_adjusted_refund_amount" lower than "min_refund_amount", the error will be returned: The proposed adjusted refund amount can not be lower than min refund amount.

4. Category Tree Update for Auto Parts for BR Sellers

The Auto Parts category tree for BR sellers has been updated starting from early November 2024. Items previously listed under the old “Auto & Moto” have now been moved to the new “Spare Parts & Accessories for Vehicles” category structure.

Please update and synchronize your system’s category tree promptly to ensure proper listing and management of products.

尊敬的开发者，

请留意以下变更：

1. 支持获取跨境投递失败包裹从当地退运仓库退回卖家的跨境物流信息

1.1 业务背景

对于跨境卖家，由于买家拒收或派送失败而投递失败的包裹 (物流状态为 LOGISTICS_DELIVERY_FAILED)，会先退回到当地退运仓库。如果包裹符合跨境退货条件，再从当地退运仓库退回给卖家。

目前，跨境卖家无法查看包裹从当地退运仓库退回卖家的物流状态。为了提升这一段物流的可视性，Shopee优化了 v2.logistics.get_tracking_info 接口，支持返回这一段物流的运单号、物流渠道名称和物流轨迹信息。

1.2 接口更新

v2.logistics.get_tracking_info 接口新增以下字段：

注意：上述字段仅适用于跨境 Failed Delivery 包裹中从当地退运仓库退回卖家的跨境运输段。

1.3 Failed Delivery 包裹物流追踪逻辑 (更新后完整逻辑)

1）本土 Failed Delivery 包裹：不涉及跨境运输，投递失败后包裹直接使用原运单号退回卖家，正向物流 (卖家 → 买家) 及完整逆向物流 (买家 → 当地退运仓库 → 卖家) 均在现有的 tracking_info 字段返回。

2）跨境 Failed Delivery 包裹：

- 正向物流 (卖家 → 买家) 及前半程逆向物流 (买家 → 当地退运仓库)：不涉及跨境运输，投递失败后包裹直接使用原运单号退回当地退运仓库，该段物流信息在现有的 tracking_info 字段返回。

- 后半程逆向物流 (当地退运仓库 → 卖家)：涉及跨境运输，系统生成新运单号，该段物流信息在新增的 reversed_tracking_number、reversed_courier_name、reversed_tracking_info 字段返回。

2. 部分物流渠道支持包裹发货前打印自画面单

2.1 业务背景

为提升卖家发货效率，部分物流渠道已支持在包裹发货前打印面单 (提前打印)，便于卖家提前准备包裹。然而，目前接口仅支持提前打印系统面单，不支持在发货前调用 v2.logistics.get_shipping_document_data_info 接口获取自画面单所需信息，导致卖家无法提前打印自画面单。

为了优化体验，Shopee 优化了 v2.logistics.get_shipping_document_data_info 接口，对于支持自画面单且允许发货前提前打印面单的包裹，卖家可以在发货前通过该接口获取自画面单所需的信息，从而提前打印自画面单，提高发货效率。

2.2 接口更新

对于支持自画面单且允许发货前提前打印面单的包裹，发货前调用 v2.logistics.get_shipping_document_data_info 接口，将不会再报错，而会返回以下字段：

· recipient_address_info

· key

· image

· shipping_document_info

· cod

· cod_amount

· order_weight

· logistics_channel_id

· shipping_carrier

· pickup_code

3. 支持获取最低可退款金额阈值

3.1 业务背景

为提升退款流程的准确性与效率，Shopee 新增“最低可退款金额阈值”规则，用于帮助卖家在为买家提供退款时，明确可退款的最低金额，避免因金额低于阈值导致退款申请失败。

3.2 接口更新

1）v2.returns.get_available_solutions 接口：新增响应字段 min_refund_amount，在 refund_amount_adjustable = true 时返回，表示该退款方案可调整的最低退款金额。

2）v2.returns.offer 接口：当卖家提交的 proposed_adjusted_refund_amount 低于 min_refund_amount 时，将返回错误提示：The proposed adjusted refund amount can not be lower than min refund amount。

4. BR 卖家的汽车配件类目树更新

BR 卖家的汽车配件类目树已于 2024 年 11 月初开始更新。原先归类在 “Auto & Moto” 下的商品，现已迁移至新的 “Spare Parts & Accessories for Vehicles” 类目结构。 请尽快更新并同步您系统中的类目树，以确保正常上架与管理商品。