Skip to main content

Convert additional address fields

Early access

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.

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

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 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.

Anchor to JavaScript clientsJavaScript 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.

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-unknown-unknown target:

    Terminal

    rustup target add wasm32-unknown-unknown

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:

First, configure your extension in your shopify.extension.toml file:

shopify.extension.toml

api_version = "2025-10"

[[extensions.targeting]]
target = "purchase.checkout.delivery-address.render-before"
module = "./src/Checkout.jsx"
export = "default"

Then, create your extension file (src/Checkout.jsx) with the following code that uses the global shopify object to update additional address fields:

JavaScript

import '@shopify/ui-extensions/preact';
import { render } from 'preact';
import { concatenateAddress1, concatenateAddress2 } from '@shopify/worldwide';

export default function extension() {
render(<Extension />, document.body);
}

function Extension() {
// 1. Generate address1 value from additional address fields
const updatedAddress1 = concatenateAddress1({
countryCode: 'BR',
streetName: 'Av. Paulista',
streetNumber: '1578',
});

// 2. Generate address2 value from additional address fields
const updatedAddress2 = concatenateAddress2({
countryCode: 'BR',
line2: 'apartamento 42',
neighborhood: 'Centro',
});

// Check if we should update the address based on city
if (shopify?.shippingAddress?.value?.city === "São Paulo") {
const newAddress = {
address1: updatedAddress1,
address2: updatedAddress2,
};

// Apply address change using global API
if (shopify?.applyShippingAddressChange) {
shopify.applyShippingAddressChange({
type: 'updateShippingAddress',
address: newAddress,
});
}
}

return null; // This extension doesn't render visible UI
}
Was this page helpful?