---
gid: dd13696b-aadc-4a51-93b9-1be276eba43e
title: Customize the address autocomplete provider
description: Build an extension to customize the address autocomplete provider for the delivery and billing address forms in checkout.
---
import CheckoutUiRequirements from 'app/views/partials/apps/checkout/ui-extensions/requirements.mdx'
import CheckoutUiCreate from 'app/views/partials/apps/checkout/ui-extensions/create.mdx'
import Deploy from 'app/views/partials/extensions/deploy.mdx'
import CheckoutUiReference from 'app/views/partials/apps/checkout/ui-extensions/reference.mdx'
import CheckoutUiPreview from 'app/views/partials/apps/checkout/ui-extensions/preview.mdx'
<Repo extension="javascript" href="https://github.com/shopify/example-checkout--address-autocomplete--js" />
<Picker name="extension">
<PickerOption name="javascript" />
</Picker>
<Overview>
You can use the [`purchase.address-autocomplete.suggest`](/docs/api/checkout-ui-extensions/2024-04/targets/address/purchase-address-autocomplete-suggest) and [`purchase.address-autocomplete.format-suggestion`](/docs/api/checkout-ui-extensions/2024-04/targets/address/purchase-address-autocomplete-format-suggestion) targets to customize the address autocomplete provider for the delivery and billing address forms in checkout. 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.
In this tutorial, you'll use checkout UI extensions to provide address suggestions from an external service.
<Notice type="shopifyPlus" title="Shopify Plus">
Checkout UI extensions are available only to [Shopify Plus](https://www.shopify.com/plus) merchants.
</Notice>
<video autoplay muted loop controls>
<source src="/assets/apps/checkout/address-autocomplete/address-autocomplete.webm" type="video/webm" />
</video>
### 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.
</Overview>
<Requirements>
<CheckoutUiRequirements />
</Requirements>
<StepSection>
<Step>
### Create a checkout UI extension
To create a checkout UI extension, use Shopify CLI, which generates starter code for building your extension.
<Substep>
<CheckoutUiCreate />
</Substep>
</Step>
<Step>
### Set up the target for the extension
Set up a target for your checkout UI extension. [Targets](/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.
<Substep>
<CodeRef
extension="javascript"
href="https://github.com/Shopify/example-checkout--address-autocomplete--js/blob/main/extensions/example-checkout-address-autocomplete-js/src/suggest.js"
tag="address-autocomplete.ext-target"
/>
#### Export the target from your script file
1. Rename the `Checkout.js` file to `suggest.js`.
2. Import the `extension` function from the `@shopify/ui-extensions/checkout` library.
3. Set the extension target to `purchase.address-autocomplete.suggest`.
4. Export this extension so it can be referenced in your configuration.
---
<Resources>
[purchase.checkout.address-autocomplete.suggest](/docs/api/checkout-ui-extensions/2024-04/targets/address/purchase-address-autocomplete-suggest)
</Resources>
</Substep>
<Substep>
<CodeRef
extension="javascript"
href="https://github.com/Shopify/example-checkout--address-autocomplete--js/blob/main/extensions/example-checkout-address-autocomplete-js/shopify.extension.toml"
tag="address-autocomplete.config-ext-target"
/>
<CheckoutUiReference />
</Substep>
</Step>
<Step>
### Auto-populate the address fields when a customer selects an address suggestion
Provide address suggestions by using the `purchase.address-autocomplete.suggest` target.
<Substep>
<CodeRef
extension="javascript"
href="https://github.com/Shopify/example-checkout--address-autocomplete--js/blob/main/extensions/example-checkout-address-autocomplete-js/src/suggest.js"
tag="address-autocomplete.attributes"
/>
### Extract attributes from the target
In the `suggest.ts` 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.
<Notice type="note">
The `selectedCountryCode` can differ between the billing and shipping address forms.
</Notice>
</Substep>
<Substep>
<CodeRef
extension="javascript"
href="https://github.com/Shopify/example-checkout--address-autocomplete--js/blob/main/extensions/example-checkout-address-autocomplete-js/src/suggest.js"
tag="address-autocomplete.fetch"
/>
### 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 [`signal`](/docs/api/checkout-ui-extensions/unstable/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.
</Substep>
<Substep>
<CodeRef
extension="javascript"
href="https://github.com/Shopify/example-checkout--address-autocomplete--js/blob/main/extensions/example-checkout-address-autocomplete-js/src/suggest.js"
tag="address-autocomplete.map"
/>
<CodeRef
extension="javascript"
href="https://github.com/Shopify/example-checkout--address-autocomplete--js/blob/main/extensions/example-checkout-address-autocomplete-js/src/suggest.js"
tag="address-autocomplete.fetch"
/>
### 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.
</Substep>
</Step>
<Step>
<CheckoutUiPreview extension="address autocomplete " extraInstruction={<Notice type="note"> This extension is non-rendering and won't appear during on your checkout</Notice>} />
<Substep>
### In the Checkout and Accounts Editor
<video autoplay muted loop controls>
<source src="/assets/apps/checkout/address-autocomplete/address-autocomplete-editor.webm" type="video/webm" />
</video>
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.
</Substep>
</Step>
<Deploy />
<NextSteps>
## 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?extension=javascript") tutorial to complete your custom address autocomplete provider.
### Next steps
<CardGrid>
<LinkCard href="/docs/api/checkout-ui-extensions/latest/apis/extensiontargets">
#### Explore the checkout UI extension targets API reference
Learn about the extension targets offered in the checkout.
</LinkCard>
<LinkCard href="/docs/apps/build/checkout/delivery-shipping/address-autocomplete/format-suggestion?extension=javascript">
#### Format address suggestions in checkout
Learn how to format address suggestions that display in checkout.
</LinkCard>
</CardGrid>
</NextSteps>
</StepSection>