Convert additional address fields

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.

The shipping address form in checkout with additional fields street name, house number, and neighborhood.

How it works

Anchor link to section titled "How 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 fields streetName and streetNumber
Replaces standard field address2 with additional fields line2 and neighborhood

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.

JavaScript clients

Anchor link to section titled "JavaScript 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.

Ruby clients

Anchor link to section titled "Ruby 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.

Requirements

Anchor link to section titled "Requirements"

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.

Rust-specific requirements

Anchor link to section titled "Rust-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 cargo-wasi:

Note

If you've previously installed cargo-wasi and updated Rust to version 1.67 or higher, then you also need to update to the latest cargo-wasi by running cargo install cargo-wasi.

Example: Performing address validations on the extended address form

Anchor link to section titled "Example: 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:

Example: Updating addresses when additional address fields are enabled

Anchor link to section titled "Example: 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: