# purchase.address-autocomplete.suggest An extension target that provides address autocomplete suggestions for address forms at checkout. Suggestions are presented to customers for delivery, billing, and pickup point addresses. The extension target must return a list of address [`suggestions`](https://shopify.dev/docs/api/checkout-ui-extensions/2024-07/targets/address/purchase-address-autocomplete-suggest#addressautocompletesuggestoutput-propertydetail-suggestions). If a formatted address is provided with each suggestion, then it will be used to auto-populate the fields in the address form when the customer selects a suggested address. Optionally, you can implement the [`purchase.address-autocomplete.format-suggestion`](https://shopify.dev/docs/api/checkout-ui-extensions/2024-07/targets/address/purchase-address-autocomplete-format-suggestion) extension target to format an address based on the address suggestion selected by the customer. > Note: > - This target does not support rendering UI components. > - This extension can only be developed as a JavaScript extension using the `ui-extensions` library. > - The [app extension configuration](https://shopify.dev/docs/apps/app-extensions/configuration) `shopify.extension.toml` file is shared between this extension target and [`purchase.address-autocomplete.format-suggestion`](https://shopify.dev/docs/api/checkout-ui-extensions/2024-07/targets/address/purchase-address-autocomplete-format-suggestion). This includes extension settings specified in the configuration file. ```js import {extension} from '@shopify/ui-extensions/checkout'; export default extension( 'purchase.address-autocomplete.suggest', async ({signal, target}) => { // 1. Use the query term the buyer entered const {field, value} = target; // 2. Fetch address suggestions const response = await fetch( `https://myapp.com/api/address-suggestions?query=${value}&field=${field}`, {signal}, ); // 3. Map response data to expected format const {data} = await response.json(); const suggestions = data.map((suggestion) => { return { id: suggestion.id, label: suggestion.label, matchedSubstrings: suggestion.matchedSubstrings, formattedAddress: { address1: suggestion.address1, address2: suggestion.address2, city: suggestion.city, zip: suggestion.zip, provinceCode: suggestion.provinceCode, countryCode: suggestion.countryCode, }, }; }); // 4. Return up to five address suggestions return { suggestions: suggestions.slice(0, 5), }; }, ); ``` ## AddressAutocompleteSuggestApi The API object provided to the `purchase.address-autocomplete.suggest` extension target. ### AddressAutocompleteSuggestApi ### signal value: `AbortSignal` The signal that the extension should listen to for cancellation requests. If the signal is aborted, the extension should cancel any ongoing requests. The signal will be aborted either when the buyer navigates away from the address field or when the debounced query value changes. Pass this signal to any asynchronous operations that need to be cancelled, like `fetch`. ### target value: `Target` The current state of the address form that the buyer is interacting with. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### Target ### field value: `'address1' | 'zip'` The `MailingAddress` field that the buyer is interacting with. This field can either be `address1` or `zip` depending on the country selected by the buyer during checkout. ### selectedCountryCode value: `CountryCode` The `countryCode` selected in the address form that the buyer is interacting with. This code is in ISO 3166 Alpha-2 format representing the buyer's country. Refer to https://www.iso.org/iso-3166-country-codes.html. ### value value: `string` The current value of the `field` the buyer is interacting with. ## Related - [APIs](https://shopify.dev/docs/api/checkout-ui-extensions/targets) - [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) - [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) ## AddressAutocompleteSuggestOutput The object expected to be returned by the `purchase.address-autocomplete.suggest` extension target. ### AddressAutocompleteSuggestOutput ### suggestions value: `AddressAutocompleteSuggestion[]` An array of address autocomplete suggestions to show to the buyer. > Note: Only the first five suggestions will be displayed to the buyer. ### AddressAutocompleteSuggestion ### formattedAddress value: `AutocompleteAddress` The address object used to auto-populate the remaining address fields. If this value is returned for every suggestion, then the `purchase.address-autocomplete.format-suggestion` extension target is not needed. ### id value: `string` A textual identifier that uniquely identifies an autocomplete suggestion or address. This identifier may be used to search for a formatted address. ### label value: `string` The address suggestion text presented to the buyer in the list of autocomplete suggestions. This text is shown to the buyer as-is. No attempts will be made to parse it. ### matchedSubstrings value: `MatchedSubstring[]` A list of substrings that matched the original search query. If `matchedSubstrings` are provided, then they will be used to highlight the substrings of the suggestions that matched the original search query. ### AutocompleteAddress A partial mailing address with only fields relevant to address autocomplete. All fields are optional ### address1 value: `string` The first line of the buyer's address, including street name and number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### address2 value: `string` The second line of the buyer's address, like apartment number, suite, etc. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### city value: `string` The buyer's city. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### countryCode value: `CountryCode` The ISO 3166 Alpha-2 format for the buyer's country. Refer to https://www.iso.org/iso-3166-country-codes.html. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### provinceCode value: `string` The buyer's province code, such as state, province, prefecture, or region. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### zip value: `string` The buyer's postal or ZIP code. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### MatchedSubstring ### length value: `number` The length of the matched substring in the suggestion label text. ### offset value: `number` The start location of the matched substring in the suggestion label text. ## Related - [APIs](https://shopify.dev/docs/api/checkout-ui-extensions/targets) - [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) - [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) ## AddressAutocompleteStandardApi The base API object provided to this and other `purchase.address-autocomplete` extension targets. ### AddressAutocompleteStandardApi ### analytics value: `Analytics` The methods for interacting with [Web Pixels](https://shopify.dev/docs/apps/marketing), such as emitting an event. ### appMetafields value: `AppMetafieldEntry[]` The metafields requested in the [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file. These metafields are updated when there's a change in the merchandise items being purchased by the customer. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). > Tip: > Cart metafields are only available on carts created via the Storefront API version `2023-04` or later.* ### attributes value: `Attribute[] | undefined` The custom attributes left by the customer to the merchant, either in their cart or during checkout. ### billingAddress value: `MailingAddress | undefined` The proposed customer billing address. The address updates when the field is committed (on change) rather than every keystroke. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### checkoutToken value: `CheckoutToken | undefined` A stable ID that represents the current checkout. Matches the `token` field in the [WebPixel checkout payload](https://shopify.dev/docs/api/pixels/customer-events#checkout) and the `checkout_token` field in the [REST Admin API `Order` resource](https://shopify.dev/docs/api/admin-rest/unstable/resources/order#resource-object). ### extension value: `Extension` The meta information about the extension. ### i18n value: `I18n` Utilities for translating content and formatting values according to the current [`localization`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization) Type 'RunnableExtensionInstance' is not assignable to type 'ExtensionInstance'. Refer to [`localization` examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#examples) for more information. ### localization value: `Localization` The details about the location, language, and currency of the customer. For utilities to easily format and translate content based on these details, you can use the [`i18n`](https://shopify.dev/docs/api/checkout-ui-extensions/apis/localization#standardapi-propertydetail-i18n) object instead. ### metafields value: `Metafield[]` The metafields that apply to the current checkout. Metafields are stored locally on the client and are applied to the order object after the checkout completes. They are shared by all extensions running on checkout, and persist for as long as the customer is working on this checkout. Once the order is created, you can query these metafields using the [GraphQL Admin API](https://shopify.dev/docs/admin-api/graphql/reference/orders/order#metafield-2021-01) ### query value: `>(query: string, options?: { variables?: Variables; version?: StorefrontApiVersion; }) => Promise<{ data?: Data; errors?: GraphQLError[]; }>` The method used to query the Storefront GraphQL API with a prefetched token. Refer to [Storefront API access examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/storefront-api) for more information. ### sessionToken value: `SessionToken` The session token providing a set of claims as a signed JSON Web Token (JWT). The token has a TTL of 5 minutes. If the previous token expires, this value will reflect a new session token with a new signature and expiry. Refer to [session token examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/session-token) for more information. ### settings value: `ExtensionSettings` The settings matching the settings definition written in the [`shopify.extension.toml`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file. Refer to [settings examples](https://shopify.dev/docs/api/checkout-ui-extensions/apis/settings#examples) for more information. > Note: The settings are empty when an extension is being installed in the [checkout editor](https://help.shopify.com/en/manual/checkout-settings/checkout-extensibility/checkout-editor). ### shippingAddress value: `MailingAddress | undefined` The proposed customer shipping address. During the information step, the address updates when the field is committed (on change) rather than every keystroke. > Note: An address value is only present if delivery is required. Otherwise, the subscribable value is undefined. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### shop value: `Shop` The shop where the checkout is taking place. ### storage value: `Storage` The key-value storage for the extension. It uses `localStorage` and should persist across the customer's current checkout session. > Caution: Data persistence isn't guaranteed and storage is reset when the customer starts a new checkout. Data is shared across all activated extension targets of this extension. In versions 2023-07 and earlier, each activated extension target had its own storage. ### version value: `Version` The runner version being used for the extension. ### Analytics ### publish value: `(name: string, data: Record) => Promise` Publish method to emit analytics events to [Web Pixels](https://shopify.dev/docs/apps/marketing). ### visitor value: `(data: { email?: string; phone?: string; }) => Promise` A method for capturing details about a visitor on the online store. ### VisitorSuccess Represents a successful visitor result. ### type value: `"success"` Indicates that the visitor information was validated and submitted. ### VisitorError Represents an unsuccessful visitor result. ### message value: `string` A message that explains the error. This message is useful for debugging. It's **not** localized, and therefore should not be presented directly to the buyer. ### type value: `"error"` Indicates that the visitor information is invalid and wasn't submitted. Examples are using the wrong data type or missing a required property. ### AppMetafieldEntry A metafield associated with the shop or a resource on the checkout. ### metafield value: `AppMetafield` The metadata information. ### target value: `AppMetafieldEntryTarget` The target that is associated to the metadata. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`. ### AppMetafield Represents a custom metadata attached to a resource. ### key value: `string` The key name of a metafield. ### namespace value: `string` The namespace for a metafield. ### type value: `string` The metafield's type name. ### value value: `string | number | boolean` The value of a metafield. ### valueType value: `'boolean' | 'float' | 'integer' | 'json_string' | 'string'` The metafield’s information type. ### AppMetafieldEntryTarget The metafield owner. ### id value: `string` The numeric owner ID that is associated with the metafield. ### type value: `| 'customer' | 'product' | 'shop' | 'shopUser' | 'variant' | 'company' | 'companyLocation' | 'cart'` The type of the metafield owner. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data) when the type is `customer`, `company` or `companyLocation`. ### Attribute ### key value: `string` The key for the attribute. ### value value: `string` The value for the attribute. ### MailingAddress ### address1 value: `string` The first line of the buyer's address, including street name and number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### address2 value: `string` The second line of the buyer's address, like apartment number, suite, etc. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### city value: `string` The buyer's city. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### company value: `string` The buyer's company name. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### countryCode value: `CountryCode` The ISO 3166 Alpha-2 format for the buyer's country. Refer to https://www.iso.org/iso-3166-country-codes.html. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### firstName value: `string` The buyer's first name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### lastName value: `string` The buyer's last name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### name value: `string` The buyer's full name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### phone value: `string` The buyer's phone number. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### provinceCode value: `string` The buyer's province code, such as state, province, prefecture, or region. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### zip value: `string` The buyer's postal or ZIP code. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### Extension ### apiVersion value: `ApiVersion` The API version that was set in the extension config file. ### capabilities value: `Capability[]` The allowed capabilities of the extension, defined in your [shopify.extension.toml](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) file. * [`api_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#api-access): the extension can access the Storefront API. * [`network_access`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#network-access): the extension can make external network calls. * [`block_progress`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#block-progress): the extension can block a customer's progress and the merchant has allowed this blocking behavior. * [`collect_buyer_consent.sms_marketing`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can collect customer consent for SMS marketing. * [`collect_buyer_consent.customer_privacy`](https://shopify.dev/docs/api/checkout-ui-extensions/configuration#collect-buyer-consent): the extension can register customer consent decisions that will be honored on Shopify-managed services. ### editor value: `Editor` The information about the editor where the extension is being rendered. If the value is undefined, then the extension is not running in an editor. ### rendered value: `boolean` A Boolean to show whether your extension is currently rendered to the screen. Shopify might render your extension before it's visible in the UI, typically to pre-render extensions that will appear on a later step of the checkout. Your extension might also continue to run after the customer has navigated away from where it was rendered. The extension continues running so that your extension is immediately available to render if the customer navigates back. If the extension is not capable of rendering UI components, then the value will always be false. ### scriptUrl value: `string` The URL to the script that started the extension target. ### target value: `Target` The identifier that specifies where in Shopify’s UI your code is being injected. This will be one of the targets you have included in your extension’s configuration file. ### version value: `string` The published version of the running extension target. For unpublished extensions, the value is `undefined`. ### Editor ### type value: `"checkout"` Indicates whether the extension is rendering in the checkout editor. ### I18n ### formatCurrency value: `(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string` Returns a localized currency value. This function behaves like the standard `Intl.NumberFormat()` with a style of `currency` applied. It uses the buyer's locale by default. ### formatDate value: `(date: Date, options?: { inExtensionLocale?: boolean; } & DateTimeFormatOptions) => string` Returns a localized date value. This function behaves like the standard `Intl.DateTimeFormatOptions()` and uses the buyer's locale by default. Formatting options can be passed in as options. ### formatNumber value: `(number: number | bigint, options?: { inExtensionLocale?: boolean; } & NumberFormatOptions) => string` Returns a localized number. This function behaves like the standard `Intl.NumberFormat()` with a style of `decimal` applied. It uses the buyer's locale by default. ### translate value: `I18nTranslate` Returns translated content in the buyer's locale, as supported by the extension. - `options.count` is a special numeric value used in pluralization. - The other option keys and values are treated as replacements for interpolation. - If the replacements are all primitives, then `translate()` returns a single string. - If replacements contain UI components, then `translate()` returns an array of elements. ### Localization ### country value: `Country | undefined` The country context of the checkout. This value carries over from the context of the cart, where it was used to contextualize the storefront experience. If the country is unknown, then the value is undefined. ### currency value: `Currency` The currency that the customer sees for money amounts in the checkout. ### extensionLanguage value: `Language` This is the customer's language, as supported by the extension. If the customer's actual language is not supported by the extension, then this is the language that is used for translations. For example, if the customer's language is 'fr-CA' but your extension only supports translations for 'fr', then the `isoCode` for this language is 'fr'. If your extension does not provide french translations at all, then this value is the default locale for your extension (that is, the one matching your .default.json file). ### language value: `Language` The language the customer sees in the checkout. ### market value: `Market | undefined` The [market](https://shopify.dev/docs/apps/markets) context of the checkout. This value carries over from the context of the cart, where it was used to contextualize the storefront experience. If the market is unknown, then the value is undefined. ### timezone value: `Timezone` The buyer’s time zone. ### Country ### isoCode value: `CountryCode` The ISO-3166-1 code for this country. ### Currency ### isoCode value: `CurrencyCode` The ISO-4217 code for this currency. ### Language ### isoCode value: `string` The BCP-47 language tag. It may contain a dash followed by an ISO 3166-1 alpha-2 region code. ### Market ### handle value: `string` The human-readable, shop-scoped identifier for the market. ### id value: `string` A globally-unique identifier for a market. ### Metafield Metadata associated with the checkout. ### key value: `string` The name of the metafield. It must be between 3 and 30 characters in length (inclusive). ### namespace value: `string` A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. This must be between 2 and 20 characters in length (inclusive). ### value value: `string | number` The information to be stored as metadata. ### valueType value: `'integer' | 'string' | 'json_string'` The metafield’s information type. ### GraphQLError GraphQL error returned by the Shopify Storefront APIs. ### extensions value: `{ requestId: string; code: string; }` ### message value: `string` ### SessionToken ### get value: `() => Promise` Requests a session token that hasn't expired. You should call this method every time you need to make a request to your backend in order to get a valid token. This method will return cached tokens when possible, so you don’t need to worry about storing these tokens yourself. ### Shop ### id value: `string` The shop ID. ### myshopifyDomain value: `string` The shop's myshopify.com domain. ### name value: `string` The name of the shop. ### storefrontUrl value: `string` The primary storefront URL. > Caution: > As of version `2024-04` this value will no longer have a trailing slash. ### Storage A key-value storage object for the extension. Stored data is only available to this specific extension and any of its instances. The storage backend is implemented with `localStorage` and should persist across the buyer's checkout session. However, data persistence isn't guaranteed. ### delete value: `(key: string) => Promise` Delete stored data by key. ### read value: `(key: string) => Promise` Read and return a stored value by key. The stored data is deserialized from JSON and returned as its original primitive. Returns `null` if no stored data exists. ### write value: `(key: string, data: any) => Promise` Write stored data for this key. The data must be serializable to JSON. ## Related - [APIs](https://shopify.dev/docs/api/checkout-ui-extensions/targets) - [Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) - [Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration)