About this plugin
OneStudio Vietnam Address for WooCommerce integrates the Vietnamese administrative address system into the WooCommerce checkout form. All Province/City, District, and Ward data is bundled with the plugin – no API key required, no dependency on an external service, no risk of interruption.
This is an independent plugin, not affiliated with, endorsed by, or sponsored by WooCommerce or Automattic. WooCommerce is a trademark of Automattic Inc.
Key features
- Vietnamese address integration: Replaces or extends WooCommerce’s default address fields with the Province/City – District – Ward system
- Supports both structures:
- Old structure (before 1 July 2025): 63 provinces with 3 levels (Province – District – Ward)
- New structure (after 1 July 2025): 34 provinces with 2 levels (Province – Ward)
- Both Classic Checkout and Block Checkout supported: see “Block Checkout support” below
- Searchable dropdowns: Province/City, District, and Ward fields are searchable (type to filter) on Classic Checkout, using the Select2 library already bundled with WooCommerce – toggleable in settings if it ever conflicts with a theme
- Bundled data: The full list of Provinces/Cities, Districts, and Wards (both structures) ships inside the plugin – works immediately after installation, no external API calls, no internet connection or API key required
- Central data server: Defaults to https://api.onestudio.vn to receive administrative changes as soon as they’re published, without needing a plugin update. Can be pointed at a self-hosted server instead, or left blank to use only the bundled data – however it’s configured, the plugin always automatically falls back to the bundled data if the server is unreachable, so checkout is never interrupted
- Automatic conversion: Converts existing orders from the old address structure to the new one, using a bundled conversion table
- Friendly interface: A complete, easy-to-use settings page inside WooCommerce Admin
- Admin display: View detailed address information on the order edit screen
Requirements
- WordPress 5.8 or later
- WooCommerce 5.0 or later
- PHP 7.4 or later
Block Checkout support
3+):
- Classic Checkout: full support for both address structures (new: Province/City → Ward, and old: Province/City → District → Ward).
- Block Checkout: new structure only (Province/City → Ward) with a real-time ward-search autocomplete field. Requires WooCommerce 8.9 or later. The old structure (with District) is currently only available on Classic Checkout.
9 and you’re using Block Checkout, the plugin shows a notice in the admin area, and you can enable “Cart and checkout shortcodes” under WooCommerce > Settings > Advanced > Features to switch to Classic Checkout.
Languages
Vietnamese and English are supported out of the box. When your site language is set to Tiếng Việt, WordPress installs and updates the Vietnamese translation automatically, with nothing to configure. org/projects/wp-plugins/onestudio-vietnam-address-for-woocommerce/
Usage
- Install and activate the plugin
- Go to WooCommerce > Vietnam Address
- Choose the default address structure (new or old)
- To convert existing orders, scroll to the “Old-to-new address conversion tool” section and click “Convert Now”
External services
vn), to fetch up-to-date Vietnamese administrative address data (provinces, wards, and old-to-new mapping tables) without requiring a plugin update whenever administrative boundaries change (renames, mergers, new codes).
g. a province or ward code) as GET request query parameters. No personal data, customer information, or order data is ever sent to this service.
When it is used: when a customer loads the checkout page (to look up province/ward lists for the address autocomplete), when a site administrator clicks “Test Connection” on the plugin’s settings page, and via a background cache-warming job that runs shortly after the API Server setting is saved (never automatically on plugin activation).
This connection is entirely optional. Leaving the “API Server” field blank, or if the server is temporarily unreachable, the plugin automatically and transparently falls back to the Vietnamese administrative address data bundled inside the plugin itself – checkout is never interrupted by this.
com/onestudiovn/onestudio-vietnam-address-api-server.
vn/terms-of-service/
vn/privacy-policy/
Support
vn
Credits
- Developed by OneStudio (https://onestudio.vn)
- Vietnamese administrative address data provided by VietMap (https://github.com/vietmap-company/vietnam_administrative_address), used under the VietMap Administrative Data License
- Built for WooCommerce