OneStudio Vietnam Address for WooCommerce

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

The plugin supports both Classic Checkout (shortcode) and Block Checkout (the default for new stores since WooCommerce 8.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.

If your WooCommerce version is older than 8.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

The plugin ships with: Vietnamese (default), English, Français, Deutsch, 日本語. Since most customers run Vietnamese-language stores, the plugin displays Vietnamese for any site without a dedicated matching translation (including sites running WordPress’s default English locale), rather than falling back to English. Sites explicitly configured for English/Français/Deutsch/日本語 still display in that language as expected.

Usage

1. Install and activate the plugin
2. Go to WooCommerce > Vietnam Address
3. Choose the default address structure (new or old)
4. To convert existing orders, scroll to the “Old-to-new address conversion tool” section and click “Convert Now”

External services

This plugin can optionally connect to a central data server, https://api.onestudio.vn, operated by the plugin author (OneStudio, https://onestudio.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).

What is sent: only administrative lookup codes (e.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.

Site owners who prefer not to connect to this service at all may run their own copy instead: the server is open source at https://github.com/onestudiovn/onestudio-vietnam-address-api-server.

Terms of Service: https://onestudio.vn/terms-of-service/
Privacy Policy: https://onestudio.vn/privacy-policy/

Support

If you need support, please visit https://onestudio.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