---
title: Format address suggestions in checkout
description: >-
  Use the purchase.address-autocomplete.format-suggestion target to format the
  selected address suggestion provided by the address autocomplete extension.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/format-suggestion?extension=polaris
  md: >-
    https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/format-suggestion.md?extension=polaris
---

# Format address suggestions in checkout

You can format the selected address suggestion provided by the [`purchase.address-autocomplete.format-suggestion`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/address/purchase-address-autocomplete-format-suggestion) extension target. The formatted address is used to auto-populate the fields of the address form. This target is used in conjunction with the [`purchase.address-autocomplete.suggest`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/address/purchase-address-autocomplete-suggest) target to provide address suggestions from an external service when the database doesn't return a formatted address.

In this tutorial, you'll use checkout UI extensions to format the suggested addresses returned by the address autocomplete extension you built in the [Customize the address autocomplete provider](https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/build-autocomplete) tutorial.

Shopify Plus

Checkout UI extensions are available only to [Shopify Plus](https://www.shopify.com/plus) merchants.

### What you'll learn

In this tutorial, you'll learn how to do the following:

* Format the selected address suggestion provided by the `purchase.address-autocomplete.format-suggestion` extension target.
* Auto-populate the fields of the shipping address form when a customer selects an address suggestion using an external address service.
* Deploy your checkout UI extension to Shopify.

## Requirements

* You're a [user with app development permissions](https://shopify.dev/docs/apps/build/dev-dashboard/user-permissions).

* You've created a new [development store](https://shopify.dev/docs/api/development-stores) with the following:

  * [Generated test data](https://shopify.dev/docs/api/development-stores/generated-test-data)
  * [Checkout and Customer Accounts Extensibility](https://shopify.dev/docs/api/developer-previews#checkout-and-customer-accounts-extensibility-developer-preview) feature preview enabled

* You've [created an app that uses Shopify CLI 3.85.1 or higher](https://shopify.dev/docs/apps/build/scaffold-app).

[Complete the 'Customize the address autocomplete provider' tutorial](https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/build-autocomplete)

Complete the [customize the address autocomplete provider tutorial](https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/build-autocomplete) to set up the address autocomplete extension. This tutorial builds on the address autocomplete extension created in the previous tutorial.

## Project

Polaris

[View on GitHub](https://github.com/shopify/example-checkout--format-suggestion--preact)

### Create a second checkout UI extension

Set up the second target for your checkout UI extension.

The `purchase.address-autocomplete.format-suggestion` extension target must be used in the same extension as the `purchase.address-autocomplete.suggest` target.

### Update the address autocomplete `suggest.js` code

Update the `suggest.js` file in the `src` directory of your address autocomplete extension that you created in the [previous tutorial](https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/address-autocomplete#set-up-the-target-for-the-extension) with this tutorial's `suggest.js` code.

## /extensions/format-suggestion/src/suggest.js

```javascript
export default async () => {
      const {field, value, selectedCountryCode} = shopify.target;
      const response = await fetchSuggestions(
        field,
        value,
        selectedCountryCode,
        shopify.signal
      );
      const { result } = await response.json();


      const suggestions = result.suggestions.map((suggestion) => {
        return {
          id: suggestion.global_address_key,
          label: suggestion.text,
          matchedSubstrings: suggestion.matched,
        };
      });


      return { suggestions };
    }


  /**
   * In this example, suggestions are fetched from a static file. In your implementation,
   * use the address field and its current query value to fetch meaningful address suggestions.
   */
  async function fetchSuggestions(_field, _value, _selectedCountryCode, signal) {
    return fetch(
      `https://shopify.github.io/address-autocomplete/address-autocomplete.json`,
      {
        // Pass `signal` to each fetch request
        signal,
      }
    );
  }
```

#### Export the extension

1. Create a new file called `format-suggestion.js` in the `src` directory of your extension that you created in the [previous tutorial](https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/address-autocomplete#set-up-the-target-for-the-extension).

2. Export this extension so it can be referenced in your configuration.

***

This tutorial uses the `purchase.address-autocomplete.format-suggestion` extension target. This target formats the selected address suggestion provided by a `purchase.address-autocomplete.suggest` target.

[purchase.checkout.address-autocomplete.format-suggestion](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/address/purchase-address-autocomplete-format-suggestion) [purchase.checkout.address-autocomplete.suggest](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/address/purchase-address-autocomplete-suggest)

## /extensions/format-suggestion/src/format-suggestion.js

```javascript
export default async () => {


  const { selectedSuggestion } = shopify.target;


  const response = await fetchSuggestions();


  const { result } = await response.json();


  const formattedAddress = result.suggestions.find(
    ({ global_address_key }) => global_address_key === selectedSuggestion.id
  );


  return formattedAddress;
};


async function fetchSuggestions() {
  return fetch(
    `https://shopify.github.io/address-autocomplete/format-suggestion.json`
  );
}
```

#### Update the extension configuration file

1. Update the `shopify.extension.toml` file to include the `format-suggestion` target.

2. Restart the server to apply the changes:

## Terminal

```bash
shopify app dev
```

## /extensions/format-suggestion/shopify.extension.toml

```toml
# Learn more about configuring your checkout UI extension:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration


# The version of APIs your extension will receive. Learn more:
# https://shopify.dev/docs/api/usage/versioning
api_version = "2025-10"


[[extensions]]
name = "format-suggestion"
handle = "format-suggestion"
type = "ui_extension"
uid = "7303ba6d-c856-9e71-e7a8-619f7b940e3a188b37a5"


# Controls where in Shopify your extension will be injected,
# and the file that contains your extension’s source code. Learn more:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/extension-targets-overview


[[extensions.targeting]]
module = "./src/suggest.js"
target = "purchase.address-autocomplete.suggest"


[[extensions.targeting]]
module = "./src/format-suggestion.js"
target = "purchase.address-autocomplete.format-suggestion"


[extensions.capabilities]
# Gives your extension access to directly query Shopify’s storefront API.
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#api-access
api_access = true


# Gives your extension access to make external network calls, using the
# JavaScript `fetch()` API. Learn more:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#network-access
# network_access = true


# Loads metafields on checkout resources, including the cart,
# products, customers, and more. Learn more:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#metafields


# [[extensions.metafields]]
# namespace = "my_namespace"
# key = "my_key"
# [[extensions.metafields]]
# namespace = "my_namespace"
# key = "my_other_key"


# Defines settings that will be collected from merchants installing
# your extension. Learn more:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#settings-definition


# [extensions.settings]
# [[extensions.settings.fields]]
# key = "banner_title"
# type = "single_line_text_field"
# name = "Banner title"
# description = "Enter a title for the banner"
```

### Format the selected address

Use the `purchase.address-autocomplete.format-suggestion` extension target to format the selected address suggestion provided by the address autocomplete extension.

### Extract the attribute from the target

In the `format-suggestion.js` file, extract the `selectedSuggestion` attribute provided by the target. This is the autocomplete suggestion that the buyer selected during checkout.

## /extensions/format-suggestion/src/format-suggestion.js

```javascript
export default async () => {


  const { selectedSuggestion } = shopify.target;


  const response = await fetchSuggestions();


  const { result } = await response.json();


  const formattedAddress = result.suggestions.find(
    ({ global_address_key }) => global_address_key === selectedSuggestion.id
  );


  return formattedAddress;
};


async function fetchSuggestions() {
  return fetch(
    `https://shopify.github.io/address-autocomplete/format-suggestion.json`
  );
}
```

### Fetch an address from an external service

Use the `selectedSuggestion` attribute to fetch the formatted address from the external address service. Return the formatted address to the checkout UI extension.

## /extensions/format-suggestion/src/format-suggestion.js

```javascript
export default async () => {


  const { selectedSuggestion } = shopify.target;


  const response = await fetchSuggestions();


  const { result } = await response.json();


  const formattedAddress = result.suggestions.find(
    ({ global_address_key }) => global_address_key === selectedSuggestion.id
  );


  return formattedAddress;
};


async function fetchSuggestions() {
  return fetch(
    `https://shopify.github.io/address-autocomplete/format-suggestion.json`
  );
}
```

### Preview the extension

Preview your extension to make sure that it works as expected.

#### Start your server

Run the Shopify CLI `dev` command to build your app and preview it on your development store.

Make sure that you select a development store that has enabled the feature preview for [Checkout and Customer Accounts Extensibility](https://shopify.dev/docs/api/developer-previews#checkout-and-customer-accounts-extensibility-developer-preview).

1. In a terminal, navigate to your app directory.

2. Either start or restart your server to build and preview your app:

   ## Terminal

   ```bash
   shopify app dev
   ```

3. Press `p` to open the developer console.

4. In the developer console page, click on the preview link for the custom format suggestion extension.

   The checkout opens.

Note

This extension is non-rendering and won't appear during on your checkout

***

This section describes how to solve some potential errors when you run `dev` for an app that contains a checkout UI extension.

### Property token error

If you receive the error `ShopifyCLI:AdminAPI requires the property token to be set`, then you'll need to use the [`--checkout-cart-url` flag](https://shopify.dev/docs/api/shopify-cli/app/app-dev#flags) to direct Shopify CLI to open a checkout session for you.

## Terminal

```terminal
shopify app dev --checkout-cart-url cart/{product_variant_id}:{quantity}
```

### Missing checkout link

If you don't receive the test checkout URL when you run `dev`, then verify the following:

* You have a development store populated with products.

* You're logged in to the correct Partners organization and development store. To verify, check your app info using the following command:

  ## Terminal

  ```terminal
  shopify app info
  ```

Otherwise, you can manually create a checkout with the following steps:

1. From your development store's storefront, add some products to your cart.

2. From the cart, click **Checkout**.

3. From directory of the app that contains your extension, run `dev` to preview your app:

   ## Terminal

   ```terminal
   shopify app dev
   ```

4. On the checkout page for your store, change the URL by appending the `?dev=https://{tunnel_url}/extensions` query string and reload the page. The `tunnel_url` parameter allows your app to be accessed using a unique HTTPS URL.

   You should now see a rendered order note that corresponds to the code in your project template.

### In the Checkout and Accounts Editor

Preview your extension in the Checkout and Accounts Editor:

1. Navigate to the **Address autocompletion** section in the **Settings** tab of the checkout and accounts editor.
2. Select your address autocomplete app.
3. Enter a house number and street name in the address field of the delivery address (for example, "1 White House").
4. Select an address suggestion in the dropdown (for example, “1 White House, Huntington NY 11743”). The delivery address fields are automatically updated.

When you're ready to release your changes to users, you can create and release an [app version](https://shopify.dev/docs/apps/launch/deployment/app-versions). An app version is a snapshot of your app configuration and all extensions.

1. Navigate to your app directory.

2. Run the following command.

   Optionally, you can provide a name or message for the version using the `--version` and `--message` flags.

   ## Terminal

   ```terminal
   shopify app deploy
   ```

Releasing an app version replaces the current active version that's served to stores that have your app installed. It might take several minutes for app users to be upgraded to the new version.

Tip

If you want to create a version, but avoid releasing it to users, then run the `deploy` command with a `--no-release` flag. You can release the unreleased app version using Shopify CLI's [`release`](https://shopify.dev/docs/api/shopify-cli/app/app-release) command, or through the Dev Dashboard.

## /extensions/format-suggestion/src/suggest.js

```javascript
export default async () => {
      const {field, value, selectedCountryCode} = shopify.target;
      const response = await fetchSuggestions(
        field,
        value,
        selectedCountryCode,
        shopify.signal
      );
      const { result } = await response.json();


      const suggestions = result.suggestions.map((suggestion) => {
        return {
          id: suggestion.global_address_key,
          label: suggestion.text,
          matchedSubstrings: suggestion.matched,
        };
      });


      return { suggestions };
    }


  /**
   * In this example, suggestions are fetched from a static file. In your implementation,
   * use the address field and its current query value to fetch meaningful address suggestions.
   */
  async function fetchSuggestions(_field, _value, _selectedCountryCode, signal) {
    return fetch(
      `https://shopify.github.io/address-autocomplete/address-autocomplete.json`,
      {
        // Pass `signal` to each fetch request
        signal,
      }
    );
  }
```

## /extensions/format-suggestion/src/format-suggestion.js

```javascript
export default async () => {


  const { selectedSuggestion } = shopify.target;


  const response = await fetchSuggestions();


  const { result } = await response.json();


  const formattedAddress = result.suggestions.find(
    ({ global_address_key }) => global_address_key === selectedSuggestion.id
  );


  return formattedAddress;
};


async function fetchSuggestions() {
  return fetch(
    `https://shopify.github.io/address-autocomplete/format-suggestion.json`
  );
}
```

## /extensions/format-suggestion/shopify.extension.toml

```toml
# Learn more about configuring your checkout UI extension:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration


# The version of APIs your extension will receive. Learn more:
# https://shopify.dev/docs/api/usage/versioning
api_version = "2025-10"


[[extensions]]
name = "format-suggestion"
handle = "format-suggestion"
type = "ui_extension"
uid = "7303ba6d-c856-9e71-e7a8-619f7b940e3a188b37a5"


# Controls where in Shopify your extension will be injected,
# and the file that contains your extension’s source code. Learn more:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/extension-targets-overview


[[extensions.targeting]]
module = "./src/suggest.js"
target = "purchase.address-autocomplete.suggest"


[[extensions.targeting]]
module = "./src/format-suggestion.js"
target = "purchase.address-autocomplete.format-suggestion"


[extensions.capabilities]
# Gives your extension access to directly query Shopify’s storefront API.
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#api-access
api_access = true


# Gives your extension access to make external network calls, using the
# JavaScript `fetch()` API. Learn more:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#network-access
# network_access = true


# Loads metafields on checkout resources, including the cart,
# products, customers, and more. Learn more:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#metafields


# [[extensions.metafields]]
# namespace = "my_namespace"
# key = "my_key"
# [[extensions.metafields]]
# namespace = "my_namespace"
# key = "my_other_key"


# Defines settings that will be collected from merchants installing
# your extension. Learn more:
# https://shopify.dev/docs/api/checkout-ui-extensions/latest/configuration#settings-definition


# [extensions.settings]
# [[extensions.settings.fields]]
# key = "banner_title"
# type = "single_line_text_field"
# name = "Banner title"
# description = "Enter a title for the banner"
```

## Tutorial complete!

Congratulations! You formatted the address autocomplete suggestions. Keep the momentum going with these related tutorials and resources.

### Next steps

[Explore the checkout UI extension targets API reference\
\
](https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/extensiontargets)

[Learn about the extension targets offered in checkout.](https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/extensiontargets)