---
title: Convert additional address fields
description: >-
  Discover how to convert between standard and extended address formats when
  additional address fields are enabled.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/delivery-shipping/additional-address-fields
  md: >-
    https://shopify.dev/docs/apps/build/checkout/delivery-shipping/additional-address-fields.md
api_name: checkout-ui-extensions
---

# Convert additional address fields

**Early access:**

Additional address fields are in early access and available by request. To request access, contact [Shopify Support](https://help.shopify.com/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](https://help.shopify.com/manual/markets/shipping-and-markets/international-considerations#additional-address) 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.](https://shopify.dev/assets/assets/images/apps/checkout/delivery-shipping/additional_address_fields/checkout-DqZ8xLKq.png)

***

## How it works

When additional address fields are enabled, [supported countries](https://help.shopify.com/manual/markets/shipping-and-markets/international-considerations#additional-address) 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](https://www.wikipedia.org/wiki/Word_joiner), alongside regional decorators.

  Shopify uses the [JavaScript](#javascript-clients) and [Ruby](#ruby-clients) libraries offered in the open source library [Worldwide](https://github.com/Shopify/worldwide) to parse the additional field data. We recommend that you use the same libraries in your app to ensure a consistent experience.

### Java​Script clients

Worldwide offers the parsing logic as an `npm` package [@shopify/worldwide](https://www.npmjs.com/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](https://www.npmjs.com/package/@shopify/worldwide).

### Ruby clients

Worldwide offers the ruby class, [`Worldwide::Address`](https://github.com/Shopify/worldwide/blob/main/lib/worldwide/address.rb), which exposes the following public methods:

* `concatenate_address1`

* `concatenate_address2`

* `split_address1`

* `split_address2`

  The usage details are described in the [README](https://github.com/Shopify/worldwide/blob/main/README.md).

***

## Requirements

* The additional address fields feature is enabled on the store.

- You're a [user with app development permissions](https://shopify.dev/docs/apps/build/dev-dashboard/user-permissions).
- You've created a [dev store](https://shopify.dev/docs/apps/build/stores/development-stores#create-a-dev-store). You can create one by running `shopify store create dev`.
- You've [created an app](https://shopify.dev/docs/apps/build/scaffold-app) using Shopify CLI. If you previously installed Shopify CLI, then make sure that you're using the [latest version](https://shopify.dev/docs/api/shopify-cli#upgrade). If you plan to create a UI for your extension, then start with the [React Router app template](https://shopify.dev/docs/api#app-templates).
- You've installed [Node.js](https://nodejs.org/en/download) 16 or higher.
- You've [installed your app](https://shopify.dev/docs/apps/build/scaffold-app#step-4-install-your-app) on the development store.

### Rust-specific requirements

The following requirements are specific to Rust-based development with Shopify Functions.

* You've installed [Rust](https://www.rust-lang.org/tools/install).

  On Windows, Rust requires the [Microsoft C++ Build Tools](https://docs.microsoft.com/en-us/windows/dev-environment/rust/setup). Make sure to select the **Desktop development with C++** workload when installing the tools.

* You've installed the [`wasm32-unknown-unknown` target](https://doc.rust-lang.org/rustc/platform-support/wasm32-unknown-unknown.html):

  ## Terminal

  ```terminal
  rustup target add wasm32-unknown-unknown
  ```

***

## 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`:

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

## shopify.extension.toml

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

```js
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
}
```

***