VietAddr – Vietnam 2-Level Address for WooCommerce

Since 1 July 2025 Vietnam uses a 2-level administrative system: 34 provinces/cities and 3,321 wards/communes/special zones. VietAddr turns the WooCommerce address form into two dependent dropdowns for Vietnamese addresses:

• Province (Tỉnh/Thành phố) uses the core state field: 34 entries.
• Ward (Xã/Phường/Đặc khu) uses the core city field, filtered by the selected province. The ward name is stored, so addresses stay readable in emails, exports and other plugins.
• Postcode is hidden for Vietnam.
• Phone numbers must have 10 digits starting with 0 or +84 (03/05/07/08/09); they are saved as 0xxxxxxxxx.

Works with:

• the Checkout block and the classic [woocommerce_checkout] shortcode,
• My Account > Addresses,
• the admin order screen (ward dropdown filtered by province),
• High-Performance Order Storage (HPOS).

Migrating from “Vietnam Checkout for WooCommerce” (woo-vietnam-checkout): Tools > “VietAddr: chuyển địa chỉ” converts saved customer addresses (old 3-level province/district/ward codes, or that plugin’s 2-level codes) to the new format. It has a dry-run mode, backs up old values to the user meta _vnck_legacy_address, and lists the addresses that need a manual fix (for example, an old ward split between several new wards). WP-CLI: wp vnck migrate-legacy [--apply].

Tiếng Việt: Plugin thay ô địa chỉ của WooCommerce bằng 2 ô chọn Tỉnh/Thành phố → Xã/Phường/Đặc khu (34 tỉnh, 3.321 xã theo đơn vị hành chính từ 01/07/2025), ẩn mã bưu chính, kiểm số điện thoại Việt Nam. Dùng được với Checkout Block, checkout cổ điển, Tài khoản > Địa chỉ, màn sửa đơn trong admin, HPOS.

Data

Administrative units are bundled in data/vn-units.json (source: provinces.open-api.vn API v2, see data/SOURCE.md). The plugin makes no external requests: the browser loads the JSON file from your own site.

Credits and data sources

• Administrative units (34 provinces/cities, 3,321 wards/communes/special zones, per the 2025 merger resolutions): source is the Vietnam National Statistics Office (Cục Thống kê, https://danhmuchanhchinh.nso.gov.vn/), downloaded through the API https://provinces.open-api.vn/ by Nguyễn Hồng Quân (https://github.com/hongquan/vn-open-api-provinces), licensed GPL-3.0-or-later. Download date and SHA-256 are in data/SOURCE.md.
• The old-to-new ward conversion table (data/legacy-map.json) also uses data from the plugin “Vietnam Checkout for WooCommerce” (woo-vietnam-checkout) 2.1.6 (GPL), and the old-ward mapping of the same API.
• This plugin is licensed GPL-3.0-or-later; the full text is in the LICENSE file.