Convert additional address fields
Additional address fields are in early access and available by request. To request access, contact Shopify Support.
Merchants can enable additional address fields for shipping and billing addresses at checkout, to comply with address standards in specific regions.
This guide introduces how to extract the additional field data from the standard address fields when additional address fields have been enabled by a merchant. Example extensions are provided for converting and updating extended address fields.

Anchor to How it worksHow it works
When additional address fields are enabled, supported countries will offer an extended address form in checkout. Depending on the country, the extended address form:
-
Replaces standard field
address1
with additional fieldsstreetName
andstreetNumber
-
Replaces standard field
address2
with additional fieldsline2
andneighborhood
The data captured in the additional fields is merged back into the standard fields. The data is joined with the Unicode format character, word joiner, alongside regional decorators.
Shopify uses the JavaScript and Ruby libraries offered in the open source library Worldwide to parse the additional field data. We recommend that you use the same libraries in your app to ensure a consistent experience.
Anchor to JavaScript clientsJava Script clients
Worldwide offers the parsing logic as an npm
package @shopify/worldwide.
The npm
package provides concatenation and splitting functions for both address1
and address2
:
-
concatenateAddress1
-
concatenateAddress2
-
splitAddress1
-
splitAddress2
The usage details are described in the README.
Anchor to Ruby clientsRuby clients
Worldwide offers the ruby class, Worldwide::Address
, which exposes the following public methods:
-
concatenate_address1
-
concatenate_address2
-
split_address1
-
split_address2
The usage details are described in the README.
Anchor to RequirementsRequirements
- The additional address fields feature is enabled on the store.
- You've created a Partner account.
- You've created a development store.
- You've created an app that uses Shopify CLI 3.49.5 or higher. If you previously installed Shopify CLI, then make sure that you're using the latest version. If you plan to create a UI for your extension, then start with the Remix app template.
- You've installed Node.js 16 or higher.
- You've installed your app on the development store.
Anchor to Rust-specific requirementsRust-specific requirements
The following requirements are specific to Rust-based development with Shopify Functions.
-
You've installed Rust.
On Windows, Rust requires the Microsoft C++ Build Tools. Make sure to select the Desktop development with C++ workload when installing the tools.
-
You've installed the
wasm32-wasip1
target:Terminal
rustup target add wasm32-wasip1
Anchor to Example: Performing address validations on the extended address formExample: Performing address validations on the extended address form
The following example checkout UI extension uses splitAddress
and the Cart and Checkout Validation API to block checkout and render an error message when the street number and neighborhood in Brazil do not meet defined conditions:
JavaScript
Anchor to Example: Updating addresses when additional address fields are enabledExample: Updating addresses when additional address fields are enabled
The following example checkout UI extension uses concatenatedAddress
and useApplyShippingAddressChange
to convert the extended address fields into the standard address fields and updates the standard address fields address1
and address2
: