# purchase.address-autocomplete.format-suggestion An extension target that formats the selected address suggestion provided by a [`purchase.address-autocomplete.suggest`](https://shopify.dev/docs/api/checkout-ui-extensions/2024-10/targets/address/purchase-address-autocomplete-suggest) target. This formatted address is used to auto-populate the fields of the address form. It must return a [`formattedAddress`](https://shopify.dev/docs/api/checkout-ui-extensions/2024-10/targets/address/purchase-address-autocomplete-format-suggestion#addressautocompleteformatsuggestionoutput-propertydetail-formattedaddress). > Caution: > This extension target is only necessary if the corresponding [`purchase.address-autocomplete.suggest`](https://shopify.dev/docs/api/checkout-ui-extensions/2024-10/targets/address/purchase-address-autocomplete-suggest) target does not provide a `formattedAddress` for the suggestions. If a formatted address is provided with each suggestion, then this target will not be called. > > If the [`purchase.address-autocomplete.suggest`](https://shopify.dev/docs/api/checkout-ui-extensions/2024-10/targets/address/purchase-address-autocomplete-suggest) target is not implemented, then this target will not work. > 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.suggest`](https://shopify.dev/docs/api/checkout-ui-extensions/2024-10/targets/address/purchase-address-autocomplete-suggest). This includes extension settings specified in the configuration file. ```js import {extension} from '@shopify/ui-extensions/checkout'; export default extension( 'purchase.address-autocomplete.format-suggestion', async ({target}) => { // 1. Use the suggestion the buyer selected const {selectedSuggestion} = target; // 2. Fetch the address parts to format the address const { address1, address2, city, zip, provinceCode, countryCode, } = await fetch( `https://myapp.com/api/fetch-address?id=${selectedSuggestion.id}`, ); // 3. Return a formatted address return { formattedAddress: { address1, address2, city, zip, provinceCode, countryCode, }, }; }, ); ``` ## AddressAutocompleteFormatSuggestionApi The API object provided to the `purchase.address-autocomplete.format-suggestion` extension target. ### AddressAutocompleteFormatSuggestionApi ### target value: `Target` The autocomplete suggestion that the buyer selected during checkout. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### Target ### selectedSuggestion value: `AddressAutocompleteSuggestion` ### 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 An address object used to auto-populate the address form fields. 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). ### 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). ### latitude value: `number` The latitude coordinates of the buyer. {% 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). ### longitude value: `number` The longitude coordinates of the buyer. {% 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) ## AddressAutocompleteFormatSuggestionOutput The object expected to be returned by the `purchase.address-autocomplete.format-suggestion` extension target. ### AddressAutocompleteFormatSuggestionOutput ### formattedAddress value: `AutocompleteAddress` The formatted address that will be used to populate the native address fields. ### AutocompleteAddress An address object used to auto-populate the address form fields. 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). ### 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). ### latitude value: `number` The latitude coordinates of the buyer. {% 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). ### longitude value: `number` The longitude coordinates of the buyer. {% 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). ## 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. * `iframe.sources`: the extension can embed an external URL in an iframe. ### 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)