---
title: Build customized address autocomplete
description: >-
  Build an extension to customize the address autocomplete provider for the
  delivery and billing address forms in checkout.
source_url:
  html: >-
    https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/build-autocomplete?extension=polaris
  md: >-
    https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/build-autocomplete.md?extension=polaris
---

# Build customized address autocomplete

To customize the address autocomplete provider for the delivery and billing address forms in checkout, use the [`purchase.address-autocomplete.suggest`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/address/purchase-address-autocomplete-suggest) and [`purchase.address-autocomplete.format-suggestion`](https://shopify.dev/docs/api/checkout-ui-extensions/latest/targets/address/purchase-address-autocomplete-format-suggestion) extension targets. For example, a merchant might want to use a custom autocomplete solution for [countries](https://help.shopify.com/manual/checkout-settings/address-collection-preferences#checkout-setup-autocomplete-orderaddress) that are not supported by Shopify.

Request access to protected customer data

To use these extension targets, you need to [request access to protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data#request-access-to-protected-customer-data) in the Dev Dashboard. Your app also needs to meet specific [requirements](https://shopify.dev/docs/apps/launch/protected-customer-data#requirements) to ensure customer privacy and security.

In this tutorial, you'll use checkout UI extensions to provide address suggestions from an external service.

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:

* Customize the list of address suggestions using an external address service that a customer sees when typing their shipping address during checkout.
* Auto-populate the fields of the shipping address form when a customer selects an address suggestion using an external address service.
* Deploy your extension code 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).

- You've [requested access to protected customer data](https://shopify.dev/docs/apps/launch/protected-customer-data#request-access-to-protected-customer-data) in the Dev Dashboard
- Your app meets specific [requirements](https://shopify.dev/docs/apps/launch/protected-customer-data#requirements) to ensure customer privacy and security.

## Project

Polaris

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

### Create a checkout UI extension

To create a checkout UI extension, use Shopify CLI, which generates starter code for building your extension.

To create a checkout UI extension, you can use Shopify CLI, which generates starter code for building your extension and automates common development tasks.

1. Navigate to your app directory:

   ## Terminal

   ```terminal
   cd <directory>
   ```

2. Run the following command to create a new checkout UI extension:

   ## Terminal

   ```terminal
   shopify app generate extension --template checkout_ui --name my-checkout-ui-extension
   ```

3. Select `Checkout UI`.

   You should now have a new extension directory in your app's directory. The extension directory includes the extension script at `src/Checkout.jsx`. The following is an example directory structure:

   ## Checkout UI extension file structure

   ```text
   └── my-app
     └── extensions
       └── my-checkout-ui-extension
           ├── src
           │   └── Checkout.jsx OR Checkout.js // The index page of the checkout UI extension
           ├── locales
           │   ├── en.default.json // The default locale for the checkout UI extension
           │   └── fr.json // The locale file for non-regional French translations
           ├── shopify.extension.toml // The config file for the checkout UI extension
           └── package.json
   ```

4. Start your development server to build and preview your app:

   ## Terminal

   ```terminal
   shopify app dev
   ```

   To learn about the processes that are executed when you run `dev`, refer to the [Shopify CLI command reference](https://shopify.dev/docs/api/shopify-cli/app/app-dev).

5. Press `p` to open the developer console. In the developer console page, click on the preview link for your extension.

### Set up the target for the extension

Set up a target for your checkout UI extension. [Targets](https://shopify.dev/docs/api/checkout-extensions/checkout#extension-targets) control where your extension renders in the checkout flow.

In your extension configuration, add the optional capabilities that you want to use. Capabilities allow you to access additional functionality in your extension.

#### Export the target from your script file

1. Rename the `Checkout.js` file to `suggest.js`.

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

***

This tutorial uses the `purchase.address-autocomplete.suggest` extension target. This target provides address autocomplete suggestions for address forms at checkout and does not support rendering UI components.

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

## /extensions/address-autocomplete/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,
        formattedAddress: suggestion.formattedAddress,
      };
    });


    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,
    }
  );
}
```

#### Reference the extension targets in your configuration file

You can define more than one target so that app users can add the extension to multiple locations in the checkout.

In your checkout UI extension's configuration file, for each of your targets, create an `[[extensions.targeting]]` section with the following information:

* `module`: The path to the file that contains the extension code.

* `target`: An identifier that specifies where you're injecting code into Shopify.

***

[`shopify.extension.toml`](https://shopify.dev/docs/apps/build/app-extensions/configure-app-extensions) is the configuration file for your extension. It contains basic information and settings.

Note

Whenever you edit your extension configuration file, you need to restart your server for the changes to take effect.

## Terminal

```bash
shopify app dev
```

## /extensions/address-autocomplete/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 = "address-autocomplete"
handle = "address-autocomplete"
type = "ui_extension"
uid = "1a57f3e4-2ce5-3c90-835b-d95646c26bac0133a86a"


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

### Auto-populate the address fields when a customer selects an address suggestion

Provide address suggestions by using the `purchase.address-autocomplete.suggest` target.

### Extract attributes from the target

In the `suggest.js` file, extract the following attributes provided by the target:

* `value` : What the customer entered in the address field.
* `field` : The autocomplete field of the shipping or billing address form that the customer is interacting with.
* `selectedCountryCode` : The country code selected in the address form that the customer is interacting with.

Note

The `selectedCountryCode` can differ between the billing and shipping address forms.

## /extensions/address-autocomplete/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,
        formattedAddress: suggestion.formattedAddress,
      };
    });


    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,
    }
  );
}
```

### Fetch address suggestions

1. Use a combination of the `value`, `selectedCountryCode`, and `field` values to fetch relevant address suggestions using your address service.

2. Pass [`shopify.signal`](https://shopify.dev/docs/api/checkout-ui-extensions/2025-07/targets/address/purchase-address-autocomplete-suggest#addressautocompletesuggestapi-propertydetail-signal) to fetch calls made by your extension. This signal can be used to cancel asynchronous operations, like network requests, as needed by Shopify.

## /extensions/address-autocomplete/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,
        formattedAddress: suggestion.formattedAddress,
      };
    });


    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,
    }
  );
}
```

### Map address suggestions

Map additional address data to the expected Shopify address format. When provided, the `formattedAddress` attribute is used to populate the appropriate fields of the shipping or billing address form after a suggestion is selected. You can return up to five address suggestions.

## /extensions/address-autocomplete/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,
        formattedAddress: suggestion.formattedAddress,
      };
    });


    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,
    }
  );
}
```

### 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 address autocomplete 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

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/address-autocomplete/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,
        formattedAddress: suggestion.formattedAddress,
      };
    });


    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/address-autocomplete/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 = "address-autocomplete"
handle = "address-autocomplete"
type = "ui_extension"
uid = "1a57f3e4-2ce5-3c90-835b-d95646c26bac0133a86a"


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

## Tutorial complete!

Nice work - what you just built could be used by Shopify merchants around the world! Keep the momentum going with these related tutorials and resources.

If your address service provides a two-step autocomplete process, then follow the [Format your address suggestions]("/docs/apps/build/checkout/delivery-shipping/address-autocomplete/format-suggestion") tutorial to complete your custom address autocomplete provider.

### 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 the checkout.](https://shopify.dev/docs/api/checkout-ui-extensions/latest/apis/extensiontargets)

[Format address suggestions in checkout\
\
](https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/format-suggestion)

[Learn how to format address suggestions that display in checkout.](https://shopify.dev/docs/apps/build/checkout/delivery-shipping/address-autocomplete/format-suggestion)