[VN] [IMPORTANT] Detailed Milestones for Vietnam Administrative Boundary Update

Dear Developers,

Following the previous announcement regarding the Vietnam Administrative Boundary changes, Shopee provides the following technical roadmap. Partners MUST complete all system compatibility adjustments during Phase 1 and Phase 2 to ensure a seamless transition before the final stabilization.

Phase 1: Gradual Live Traffic Deployment (Gray-scale)

Timeline: 04 Mar 2026 - 10 Mar 2026

What to Expect: New boundary data and logic will be enabled gradually across live traffic.

Potential Issues:

- Data Inconsistency: API responses may return a mix of old and new region/state/city/address/zipcode/district/town names. Some address will show vn_data_version: “new” while others remain “old”.

- Logic Shift: Delivery estimates (EDD/EDT) will transition to new administrative boundary calculations.

Solutions / Action Required:

- Adopt Mapping Tables: Since address IDs remain unchanged, your system must re-fetch and update the display names (text fields) from Shopee APIs to ensure consistency. Reference the mapping data fields in the previous announcement to ensure your system recognizes both ID versions.

- Dynamic Rendering: Do not use local hard-coded lists to validate or filter API responses. Your system must render whichever name/ID the API returns in real-time.

Phase 2: System-Wide Data Migration (Data Fix)

Timeline: 11 Mar 2026 - 29 Mar 2026

What to Expect: Shopee will automatically update ~288 million existing addresses to the new structure.

Potential Issues:

- Migration Failure (~2%): Addresses with insufficient data will fail to auto-migrate.

- Inaccuracy Risk (~4.9%): Some addresses might be mapped with lower accuracy (low confidence).

Solutions / Action Required:

- Error Handling: If APIs (e.g., v2.logistics.ship_order) return an "Invalid Address" error, your system must trigger a clear notification to the Seller.

- Manual Correction: Guide the Seller to the Shopee App, Website, or Seller Centre to re-select and save their address, which will automatically update it to the new, compliant version.

- Please refer to this announcement on the Seller Education Hub for references

Phase 3: Full Go-Live & Stabilization

Timeline: To be announced (Subject to final notification)

What to Expect: Full traffic switch and completion of all data migration.

Solutions / Action Required:

- Final Verification: This stage marks the official completion. If compatibility was successfully implemented during Phases 1 & 2, no further development is required. Please continue to monitor your integration logs for any unexpected errors.

尊敬的开发者：

继之前关于越南行政区划变更的公告，Shopee 提供以下技术实施阶段供参考。

您必须在第一阶段和第二阶段完成所有系统兼容性调整，以确保在最终稳定版本上线前平稳过渡。

阶段一：流量灰度上线

时间：2026 年 3 月 4 日 - 2026 年 3 月 10 日

预期情况：新行政区划数据与逻辑将在线上流量中逐步启用。

可能出现的问题：

- 数据不一致： API返回结果可能混合显示旧版与新版 region/state/city/address/zipcode/district/town名称。有些地址会显示 vn_data_version:"new"，而部分地址仍为 "old"。

- 逻辑变化：配送预计时间（EDD/EDT）将根据新的行政区划进行计算。

解决方案 / 必要操作：

- 采用映射表：由于地址 ID 保持不变，您的系统需重新获取并更新 Shopee API 返回的文本名称，以保证数据一致。可参考之前公告中的映射数据字段，确保系统能识别两种 ID 版本。

- 动态渲染：不要使用本地硬编码列表来校验或过滤 API 返回结果，系统需实时渲染 API 返回的任意地址相关的名称或 ID。

阶段二：系统数据迁移

时间：2026 年 3 月 11 日 - 2026 年 3 月 29 日

预期情况：Shopee 将自动将约 2.88 亿条现有地址更新为新结构。

可能出现的问题：

- 迁移失败（约 2%）：部分地址因数据不足无法自动迁移。

- 精度风险（约 4.9%）：部分地址可能映射精度较低（低置信度）。

解决方案 / 必要操作：

- 错误处理：若 API（如 v2.logistics.ship_order）返回 “Invalid Address” 错误，系统需触发明确通知给卖家。

- 手动修正：引导卖家在 Shopee App、网站或 Seller Centre 重新选择并保存地址，系统将自动更新为符合新结构的版本。

更多参考内容，请访问 Seller Education Hub 查看本公告。

阶段三：全面上线与稳定

时间：待公告（最终通知为准）

预期情况：完成全量流量切换及所有数据迁移。

解决方案 / 必要操作：

- 最终验证：此阶段标志正式完成。如果在第一、二阶段已成功实施兼容性，无需额外开发操作，建议继续监控集成日志，可以感知到任何意外错误。