[Important] Support 3PF Multi-warehouse Mode

Dear Developers,

Based on the support for 3PF shop mode, Shopee facilitated 3PF multi-warehouse model where single items can be stocked and fulfilled across multiple local 3PF warehouses within the same region. 3PF sellers can associate multiple local 3PF warehouses to single shop (including Pure - 3PF Shop and PFF - 3PF Shop) in single region, which enable 3PF sellers to have the flexibility to manage the product inventory and order fulfillment according to their actual business needs.

After this upgrade of 3PF multi-warehouse model, the API call flow remains unchanged (please refer to: https://open.shopee.com/announcements/785). However, please note that existing API responses will reflect multiple 3PF warehouse stock locations once sellers adopt the 3PF multi-warehouse model.

The Open API updates are as follows:

Response updates of existing API

1. The warehouse list returned by v2.merchant.get_merchant_warehouse_location_list & v2.merchant.get_merchant_warehouse_list

If a CNSC seller, the merchant contains the following shops:

For the above merchant, the API will return the following warehouse list:

{

"response": [

{

"location_id": "MY000001Z",

"warehouse_name": "Warehouse A"

},

{

"location_id": "MY000002Z",

"warehouse_name": "Warehouse B"

},

{

"location_id": "MY000003Z",

"warehouse_name": "Warehouse C"

},

{

"location_id": "CNZ",

"warehouse_name": "Warehouse D"

},

{

"location_id": "SG000001Z",

"warehouse_name": "Warehouse E"

},

{

"location_id": "SG000002Z",

"warehouse_name": "Warehouse F"

}

]

}

2. The stock info returned by v2.product.get_item_base_info & v2.product.get_model_list

For the above merchant, if the Category/Attribute/Brand set when creating MTSKU can be sold as both local and CB products in MY and SG regions, and the stock is set:

- CNZ：600

- MY000001Z：500

- MY000002Z：400

- MY000003Z：300

- SG000001Z：200

- SG000002Z：100

After publishing the above MTSKU to MY Shop 1 and SG Shop 2, the stock will be:

Assuming that the stock limit of MTSKU is 0-10000, and SG Shop 2 has set the reserved stock to 200, when updating the stock of MTSKU:

- The sum stock of CNZ + MY000001Z + MY000002Z + MY000003Z + SG000001Z + SG000002Z needs to be less than or equal to 10000;

- The sum stock of CNZ + SG000001Z + SG000002Z needs to be greater than 200.

3. The fulfillment warehouse returned by v2.order.get_order_detail

Take SG Shop 2 as an example:

For orders from this shop:

- If product_location_id returns SG000001Z, this order should be fulfilled from local warehouse Warehouse E;

- If product_location_id returns SG000002Z, this order should be fulfilled from local warehouse Warehouse F;

- If product_location_id returns CNZ, this order should be fulfilled from CB warehouse Warehouse D.

Support New API v2.order.get_warehouse_filter_config

Previously, Shopee launched the v2.order.search_package_list, which supports filtering the packages that have not been SHIPPED across different warehouses using product_location_ids.

Normally, you can use the v2.shop.get_warehouse_detail to retrieve the product_location_id corresponding to the shop's warehouses for filtering. However, this API will only return the currently linked warehouses and may miss some edge cases (e.g., warehouses that have been unlinked but still retain packages that have not been SHIPPED).

To address this issue, we provide the v2.order.get_warehouse_filter_config. For multi-warehouse shops, this API will return all warehouses with packages that have not been SHIPPED along with the corresponding product_location_id. You can choose to integrate this API based on your business needs.

Related APIs:

v2.merchant.get_merchant_warehouse_location_list

v2.merchant.get_merchant_warehouse_list

v2.product.get_item_base_info

v2.product.get_model_list

v2.order.get_order_detail

v2.order.get_warehouse_filter_config

Effective Date on Live:

2025.03.05

尊敬的开发者，

您好，在支持本地化履约三方仓库 (3PF) 的一店多运模式的基础上，Shopee 会进一步支持单品在单个地区进行多个本地三方仓库备货履约的模式，卖家可以根据业务实际需求，对 3PF 店铺 (包括 Pure - 3PF Shop 和 PFF - 3PF Shop) 进行多个本地三方仓库地址关联，并对店铺商品进行多个仓库库存管理。

本次模式升级后，正常情况下 API 调用流程无变化 (可参考：https://open.shopee.com/announcements/785)，但请留意已有接口的返回结果会随着卖家使用单个地区单品多仓备货履约模式后，返回多个三方仓库存地址情况。

具体接口更新如下：

已有接口返回结果更新

1）v2.merchant.get_merchant_warehouse_location_list & v2.merchant.get_merchant_warehouse_list 返回的仓库列表

假如某CNSC卖家，Merchant 包含以下店铺：

针对上述 Merchant，接口返回的仓库列表如下：

{

"response": [

{

"location_id": "MY000001Z",

"warehouse_name": "Warehouse A"

},

{

"location_id": "MY000002Z",

"warehouse_name": "Warehouse B"

},

{

"location_id": "MY000003Z",

"warehouse_name": "Warehouse C"

},

{

"location_id": "CNZ",

"warehouse_name": "Warehouse D"

},

{

"location_id": "SG000001Z",

"warehouse_name": "Warehouse E"

},

{

"location_id": "SG000002Z",

"warehouse_name": "Warehouse F"

}

]

}

2）v2.product.get_item_base_info & v2.product.get_model_list 返回的库存情况

针对上述 Merchant，若创建 MTSKU 时，设置的 Category/Attribute/Brand 在 MY 和 SG 地区既可以作为本地商品销售也可以作为跨境商品销售时，并且设置库存为：

- CNZ：600

- MY000001Z：500

- MY000002Z：400

- MY000003Z：300

- SG000001Z：200

- SG000002Z：100

将上述 MTSKU 发布至 MY Shop 1 和 SG Shop 2后，接口返回的库存值如下：

假设全球商品的库存合法值为 0-10000，SG Shop 2 设置了活动库存为 200， 则更新上述 MTSKU 的库存时：

- CNZ + MY000001Z + MY000002Z + MY000003Z + SG000001Z + SG000002Z 库存总和需小于等于 10000；

- CNZ + SG000001Z + SG000002Z 库存需大于200。

3）v2.order.get_order_detail 返回的履约仓库

以上述 SG Shop 2 为例：

该店铺产生的订单中：

- 若 product_location_id 返回 SG000001Z，则该订单应该从本地仓库 Warehouse E 履约；

- 若 product_location_id 返回 SG000002Z，则该订单应该从本地仓库 Warehouse F 履约；

- 若 product_location_id 返回 CNZ，则该订单应该从跨境仓库 Warehouse D 履约。

新增接口 v2.order.get_warehouse_filter_config

此前，Shopee上线了 v2.order.search_package_list 接口，支持通过 product_location_ids 筛选不同仓库下未完成发货的包裹列表。

通常情况下，可以通过 v2.shop.get_warehouse_detail 接口，获取店铺仓库列表对应的 product_location_id 进行筛选，但是该接口只会返回店铺下当前绑定的仓库列表，而不会返回部分边缘场景的仓库列表 (例如：已解除绑定但仍存在未完成发货包裹的仓库)。

为了解决这一问题，我们新增了 v2.order.get_warehouse_filter_config 接口，针对 Multi-warehouse 店铺返回店铺下所有未完成发货包裹的仓库列表及其 product_location_id，您可以根据实际业务需求选择是否对接该接口。

影响接口：

v2.merchant.get_merchant_warehouse_location_list

v2.merchant.get_merchant_warehouse_list

v2.product.get_item_base_info

v2.product.get_model_list

v2.order.get_order_detail

v2.order.get_warehouse_filter_config

上线时间：

2025.03.05