[IMPORTANT] System Requirements for Vietnam Administrative Boundary Changes

Dear Developers,

Shopee would like to inform you that, based on the latest government regulations, we plan to update Vietnam’s administrative boundary data across the entire Shopee Open Platform system.

This announcement is primarily intended for technical preparation. Please complete system modification and verification in the Sandbox environment to avoid shipment failures, system disruptions, or other operational risks after the official release.

ADDRESS DISPLAY DATA UPDATE (CRITICAL)

Update Mechanism:

Shopee will automatically update the system. Address-related IDs (such as address_id, location_id, warehouse_id) will remain unchanged. Only the address field values (state, city, district, town, and the complete address string formed by concatenating these fields) associated with these IDs will be updated.

Risk:

If your system caches the mapping between IDs and address names, it may result in:

Address display remaining as outdated names, causing inconsistency with Shopee data
Failures or blocking occurring in subsequent fulfillment processes

Example:

Before the update, ID 123 = "District 2".
After the update, ID 123 = "Ward An Khanh".

If you rely on cache, the displayed address name is still the old one, which is inconsistent with Shopee's actual data. This leads to failures or blockages in subsequent fulfillment processes.

Action Required:

Resynchronize all address names (text data) and full address strings in your database to comply with the new government administrative boundaries, ensuring compatibility with Shopee’s updated address names (fields: state, city, district, town, address).
Ensure all address-related fields (state, city, district, town, address) in your system are updated to prevent validation or shipment issues.

LOGIC REVIEW & BEST PRACTICES

Partners are requested to verify modules with logic dependent on location names:

Shipping routing (Driver Zone / Hub Mapping): Re-map newly updated areas (Example: merged wards/communes must be correctly mapped to the appropriate Hub).
Shipping fee configuration (Shipping Fee Rules): Review free/reduced shipping rules currently set based on old District/Ward names.
Reporting & Reconciliation (Reporting): Ensure historical data and new data are correctly mapped to avoid inaccuracies in revenue reports by region.
Validation Logic (Important): We strongly recommend NOT using hard-coded location names (static text) to block or validate orders.

Recommendation: Please rely on IDs or update your mapping logic to align with the new Government standard names.

TECHNICAL REFERENCES

3.1 New field vn_data_version

Description:

Added vn_data_version field to v2.logistics.get_address_list to indicate the status of address data, helping developers determine whether the data has been updated to the latest administrative boundaries.

Field Description:

Name	Type	Description
vn_data_version	string	Enumerated values: old: old administrative district address new: updated to the new administrative district address

Data Update Mechanism:

Shopee will automatically update existing address data to the new administrative boundaries.
Addresses successfully updated will have vn_data_version = "new".
If "old" is returned, it indicates the address could not be automatically migrated (e.g., due to missing coordinates). In this case, Partners should guide Sellers to manually update their address information to trigger the system refresh. This can be done via Shopee Seller Center or by calling the relevant Open API update endpoints corresponding to the specific address type (e.g., v2.logistics.update_address, etc.).

Example Response:

{

"error": "",

"message": "",

"request_id": "e3e3e7f347380eed31461ae7a9051f00:010001516a00ba46:0000004a57447c1a",

"response": {

"address_list": [

{

"address": "Số 14, Hẻm 2 Trần Não, Khu Phố 2, Phường An Khánh, Thành phố Hồ Chí Minh, Việt Nam",

"address_id": 20474,

"address_type": [

"DEFAULT_ADDRESS",

"PICKUP_ADDRESS",

"RETURN_ADDRESS"

"city": "Phường An Khánh",

"district": "",

"region": "VN",

"state": "Thành phố Hồ Chí Minh",

"town": "",

"vn_data_version": "new",

"zipcode": ""

}

"show_pickup_address": false

}

3.2 Blocking Mechanism Error Response (For Future Block Phase)

In API calls, if addresses that have not been updated to the new administrative boundaries (vn_data_version = "old") are used, calls to v2.logistics.ship_order or v2.logistics.mass_ship_order will be blocked and return the following error message: "Some addresses are no longer supported per new regulation, please update to avoid wrong fulfilment"

Note: Actual error codes or message formats may be adjusted upon official release; please follow subsequent announcements.

3.3 Affected APIs

Note: This list is for reference. Partners are required to check all APIs that return or consume address data.

v2.shop.get_warehouse_detail

v2.merchant.get_merchant_warehouse_list

v2.order.get_order_detail

v2.order.get_package_detail

v2.order.get_booking_detail

v2.order.get_warehouse_filter_config

v2.order.get_buyer_invoice_info

v2.logistics.get_shipping_parameter

v2.logistics.get_mass_shipping_parameter

v2.logistics.get_booking_shipping_parameter

v2.logistics.get_shipping_document_data_info

v2.logistics.get_booking_shipping_document_data_info

v2.logistics.ship_order

v2.logistics.mass_ship_order

v2.logistics.ship_booking

v2.logistics.update_shipping_order

v2.logistics.get_address_list

v2.logistics.update_address

v2.logistics.delete_address

v2.logistics.set_address_config

v2.returns.get_return_detail

TESTING REQUIREMENTS

Sandbox Testing:

26/01/2026 - 06/02/2026

During this period, please conduct technical reviews and integration tests on the Sandbox to verify system integration and logic processing.

Display new administrative names correctly
Recognize vn_data_version
Encounter an error when calling v2.logistics.ship_order and v2.logistics.mass_ship_order due to an outdated address

IMPORTANT:

Sandbox Account Usage: The new location data and blocking logic have been pre-configured for existing Sandbox Shops. To ensure immediate access to testing features, please use your currently available Sandbox accounts.

Do not create new Sandbox shops for this testing purpose unless you have absolutely no prior account.
Exception: If you must create a new shop, you will need to submit a request via the Open Platform Support Channel to manually enable the configuration (processing time applies).

For reference: Sandbox Testing v2

GO-LIVE TIME

The official release of the new fields and address data updates will be announced in a subsequent notification.

DISCLAIMER

The above items are suggestions based on common operational models. Partners are requested to comprehensively review their internal systems.

Please be advised that failure to update your system in accordance with these changes will result in direct operational disruptions for your connected Sellers and 3PL partners.

Potential Impacts: Inability to arrange shipment, AWB printing errors, failed pickups due to data mismatch, and inaccurate routing.
Liability: Shopee shall not be liable for any operational incidents or losses arising from the Partner's failure to ensure system compatibility by the Go-live date. Partners are solely responsible for ensuring their integration is ready to support Sellers seamlessly.

For technical inquiries, please respond via the Shopee Open Platform Support Channel.

Shopee Open Platform Team

尊敬的开发者，

Shopee 现通知您，依据最新政府法规，我们计划在整个 Shopee Open Platform 系统中更新越南的行政区划数据。

本公告主要用于技术准备阶段。请您务必在 Sandbox 阶段完成系统改造与验证，以避免正式上线后出现发货失败、接口拦截或其他运营风险。

1.地址显示数据更新（关键）

更新机制： Shopee 系统将自动执行地址数据更新，所有地址相关 ID（如 address_id、location_id、warehouse_id）保持不变，仅更新与这些 ID 关联的地址字段值（state、city、district、town以及由这些字段拼接生成的完整地址字符串）

风险：

如果您的系统缓存了 ID 与地址名称的映射关系，则可能导致：

显示仍为旧地址名称，与 Shopee 实际数据不一致
在后续的履约等环节出现失败或拦截

示例：

更新前，ID 123 = "District 2"
更新后，ID 123 = "Ward An Khanh"

若依赖缓存，仍会显示“District 2”，可能导致校验错误。

操作要求：

重新同步您的数据库中所有地址名称（文本数据）及完整地址字符串，以符合新的政府行政区划，并确保与 Shopee 系统处理的新地址名称兼容（参考字段 state、city、district、town、address）。
确保您的系统中所有与地址相关的字段（state、city、district、town）同步更新，避免校验或发货问题。

逻辑审核与最佳实践

您需要验证依赖地址名称的模块：

发货路由：重新映射更新区域（合并的地址必须正确映射到对应 Hub）。
运费配置：检查基于旧District/Ward 名称设置的免费或减免运费规则。
报表与对账：确保历史数据和新数据正确映射，避免按区域的收入报表出现偏差。
校验逻辑：强烈建议不要使用硬编码的地址名称来阻止或校验订单。

建议：逻辑判断建议使用ID 或更新映射逻辑，以符合新的政府标准名称。

技术参考

3.1 新字段 vn_data_version

描述：

在 v2.logistics.get_address_list 中新增vn_data_version参数用于标识地址数据状态，帮助开发者判断数据是否已更新到最新行政区域。

字段说明：

Name	类型	描述
vn_data_version	string	枚举值： old：旧行政区地址 new：已更新至新行政区地址

数据更新机制：

Shopee 系统将自动尝试将已有地址更新至新的行政区划。
更新成功的地址其 vn_data_version 将显示为 "new"。
如果返回“old”，则表示该地址无法自动更新（例如，由于缺少坐标信息）。在这种情况下，您应指导卖家手动更新地址信息以触发系统刷新。卖家可以通过 Shopee 卖家中心或调用与特定地址类型对应的 Open API 更新端点（例如，v2.logistics.update_address 等）来完成此操作。

示例响应：

{

"error": "",

"message": "",

"request_id": "e3e3e7f347380eed31461ae7a9051f00:010001516a00ba46:0000004a57447c1a",

"response": {

"address_list": [

{

"address": "Số 14, Hẻm 2 Trần Não, Khu Phố 2, Phường An Khánh, Thành phố Hồ Chí Minh, Việt Nam",

"address_id": 20474,

"address_type": [

"DEFAULT_ADDRESS",

"PICKUP_ADDRESS",

"RETURN_ADDRESS"

"city": "Phường An Khánh",

"district": "",

"region": "VN",

"state": "Thành phố Hồ Chí Minh",

"town": "",

"vn_data_version": "new",

"zipcode": ""

}

"show_pickup_address": false

}

3.2 拦截机制错误响应

在 API 调用中，如果使用尚未更新到新行政边界的地址（vn_data_version = "old"），调用 v2.logistics.ship_order 或 v2.logistics.mass_ship_order 时将被阻止，并返回错误信息： "Some addresses are no longer supported per new regulation, please update to avoid wrong fulfilment"

注意：实际错误代码或消息格式可能会在正式上线后后进行调整，请关注后续公告。

3.3 受影响的 API

所有读取、使用或更新地址信息的接口均可能受到影响，不限于以下列表：

v2.shop.get_warehouse_detail

v2.merchant.get_merchant_warehouse_list

v2.order.get_order_detail

v2.order.get_package_detail

v2.order.get_booking_detail

v2.order.get_warehouse_filter_config

v2.order.get_buyer_invoice_info

v2.logistics.get_shipping_parameter

v2.logistics.get_mass_shipping_parameter

v2.logistics.get_booking_shipping_parameter

v2.logistics.get_shipping_document_data_info

v2.logistics.get_booking_shipping_document_data_info

v2.logistics.ship_order

v2.logistics.mass_ship_order

v2.logistics.ship_booking

V2.logistics.update_shipping_order

v2.logistics.get_address_list

v2.logistics.update_address

v2.logistics.delete_address

v2.logistics.set_address_config

v2.returns.get_return_detail

4.Sandbox 测试安排（强制参与）

测试时间：

2026/01/26 - 06/02/2026

在此期间，请您在 Sandbox 上进行技术评审和集成测试，验证系统集成与逻辑处理。

测试要求：

能正确展示新行政区名称
能识别 vn_data_version
因为地址已过期，调用 v2.logistics.ship_order 和 v2.logistics.mass_ship_order 时遇到错误。

重要说明：

Sandbox账号使用：新的地址数据和屏蔽逻辑已预先配置到现有的Sandbox店铺中。为确保您能立即体验测试功能，请使用您当前可用的Sandbox账号。

除非您之前没有任何账号，否则请勿为此测试目的创建新的Sandbox店铺。
例外情况：如果您必须创建新店铺，则需要通过Shopee Open Platform Support Channel提交请求以手动启用配置（需要一定的处理时间）。

5.上线时间

新增字段和地址数据更新正式上线，我们会在后续公告中通知。

6.责任声明

上述条目基于常见运营模型提出建议，您需全面审查内部系统。

未按要求更新系统可能导致连接的卖家和 3PL 合作伙伴运营受阻。

潜在影响：无法安排发货、运单打印错误、因数据不匹配导致取件失败以及路线不准确。
责任申明：Shopee 对合作伙伴未在上线前确保系统兼容而导致的任何事故或损失不承担责任。合作伙伴需自行确保集成准备就绪，以无缝支持卖家。

如有相关技术问题，请咨询Shopee Open Platform Support Channel。

Shopee Open Platform Team

[IMPORTANT] System Requirements for Vietnam Administrative Boundary Changes

资料正文

§1 [IMPORTANT] System Requirements for Vietnam Administrative Boundary Changes