--- title: Addresses API description: The API for interacting with addresses. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/addresses-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/addresses-api.md --- # Addresses API **Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data).:** The API for interacting with addresses. ### Support Targets (33) ### Supported targets * purchase.​address-autocomplete.​format-suggestion * purchase.​address-autocomplete.​suggest * purchase.​checkout.​actions.​render-before * purchase.​checkout.​block.​render * purchase.​checkout.​cart-line-item.​render-after * purchase.​checkout.​cart-line-list.​render-after * purchase.​checkout.​chat.​render * purchase.​checkout.​contact.​render-after * purchase.​checkout.​delivery-address.​render-after * purchase.​checkout.​delivery-address.​render-before * purchase.​checkout.​footer.​render-after * purchase.​checkout.​header.​render-after * purchase.​checkout.​payment-method-list.​render-after * purchase.​checkout.​payment-method-list.​render-before * purchase.​checkout.​pickup-location-list.​render-after * purchase.​checkout.​pickup-location-list.​render-before * purchase.​checkout.​pickup-location-option-item.​render-after * purchase.​checkout.​pickup-point-list.​render-after * purchase.​checkout.​pickup-point-list.​render-before * purchase.​checkout.​reductions.​render-after * purchase.​checkout.​reductions.​render-before * purchase.​checkout.​shipping-option-item.​details.​render * purchase.​checkout.​shipping-option-item.​render-after * purchase.​checkout.​shipping-option-list.​render-after * purchase.​checkout.​shipping-option-list.​render-before * purchase.​thank-you.​announcement.​render * purchase.​thank-you.​block.​render * purchase.​thank-you.​cart-line-item.​render-after * purchase.​thank-you.​cart-line-list.​render-after * purchase.​thank-you.​chat.​render * purchase.​thank-you.​customer-information.​render-after * purchase.​thank-you.​footer.​render-after * purchase.​thank-you.​header.​render-after ## StandardApi The base API object provided to `purchase` extension targets. * **billingAddress** **SubscribableSignalLike\** The proposed customer billing address. The address updates when the field is committed (on change) rather than every keystroke. The property is available only if the extension has access to protected customer data. The subscribable value is `undefined` if the billing address hasn't been provided yet. [](https://shopify.dev/apps/store/data-protection/protected-customer-data)Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). * **shippingAddress** **SubscribableSignalLike\** The proposed customer shipping address. During the information step, the address updates when the field is committed (on change) rather than every keystroke. The property is available only if the extension has access to protected customer data. When available, the subscribable value is `undefined` if delivery isn't required. [](https://shopify.dev/apps/store/data-protection/protected-customer-data)Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### SubscribableSignalLike Represents a reactive signal interface that provides both immediate value access and subscription-based updates. Enables real-time synchronization with changing data through the observer pattern. This interface extends \`ReadonlySignalLike\` with deprecated fields that are still supported for backwards compatibility. * current The current value of the signal. Equivalent to \`.value\`, accessing this property subscribes to changes when used in a reactive context. ```ts T ``` * destroy Cleans up the subscription and releases any resources held by this signal. After calling \`destroy()\`, the signal stops receiving updates from the main thread. ```ts () => Promise ``` * subscribe Subscribes to value changes and calls the provided function whenever the value updates. Returns an unsubscribe function to clean up the subscription. Use to automatically react to changes in the signal's value. ```ts (fn: (value: T) => void) => () => void ``` * value The current value of the signal. This property provides immediate access to the current value without requiring subscription setup. Use for one-time value checks or initial setup. ```ts T ``` ### MailingAddress * address1 The first line of the street address, including the street number and name. The value is \`undefined\` if the buyer hasn't entered an address yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * address2 The second line of the buyer's address, such as apartment number, suite, or unit. The value is \`undefined\` if the buyer didn't provide a second address line. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * city The city, town, or village of the address. The value is \`undefined\` if the buyer hasn't entered a city yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * company The buyer's company name. The value is \`undefined\` if the buyer didn't enter a company or the store doesn't collect company names. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * countryCode The two-letter country code in \[ISO 3166 Alpha-2]\(https://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2) format. The value is \`undefined\` if the buyer hasn't selected a country yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts CountryCode ``` * firstName The buyer's first name. Use this alongside \`lastName\` when you need to display or process name parts separately. The value is \`undefined\` if the buyer didn't provide a first name or the store doesn't collect split names. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * lastName The buyer's last name. Use this alongside \`firstName\` when you need to display or process name parts separately. The value is \`undefined\` if the buyer didn't provide a last name or the store doesn't collect split names. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * name The buyer's full name, typically a combination of first and last name. The value is \`undefined\` if the buyer didn't provide a name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * phone The phone number associated with the address, typically in international format. The value is \`undefined\` if the buyer didn't provide a phone number or the store doesn't collect phone numbers. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * provinceCode The province, state, prefecture, or region code of the address. The format varies by country. The value is \`undefined\` if the buyer hasn't selected one yet or the country doesn't have provinces. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * zip The postal code or ZIP code of the address, used for mail sorting and delivery routing. The value is \`undefined\` if the buyer hasn't entered one yet or the country doesn't use postal codes. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` ### CountryCode ```ts 'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AN' | 'AO' | 'AR' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BV' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GS' | 'GT' | 'GW' | 'GY' | 'HK' | 'HM' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PN' | 'PS' | 'PT' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TA' | 'TC' | 'TD' | 'TF' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'UM' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW' | 'ZZ' ``` ### ShippingAddress * address1 The first line of the street address, including the street number and name. The value is \`undefined\` if the buyer hasn't entered an address yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * address2 The second line of the buyer's address, such as apartment number, suite, or unit. The value is \`undefined\` if the buyer didn't provide a second address line. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * city The city, town, or village of the address. The value is \`undefined\` if the buyer hasn't entered a city yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * company The buyer's company name. The value is \`undefined\` if the buyer didn't enter a company or the store doesn't collect company names. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * countryCode The two-letter country code in \[ISO 3166 Alpha-2]\(https://en.wikipedia.org/wiki/ISO\_3166-1\_alpha-2) format. The value is \`undefined\` if the buyer hasn't selected a country yet. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts CountryCode ``` * firstName The buyer's first name. Use this alongside \`lastName\` when you need to display or process name parts separately. The value is \`undefined\` if the buyer didn't provide a first name or the store doesn't collect split names. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * lastName The buyer's last name. Use this alongside \`firstName\` when you need to display or process name parts separately. The value is \`undefined\` if the buyer didn't provide a last name or the store doesn't collect split names. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * name The buyer's full name, typically a combination of first and last name. The value is \`undefined\` if the buyer didn't provide a name. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * oneTimeUse Controls whether the address is saved to the buyer's account. When \`true\`, the address won't be saved and is only used for this checkout. When \`false\` or \`undefined\`, the address might be saved to the buyer's account for future use. ```ts boolean ``` * phone The phone number associated with the address, typically in international format. The value is \`undefined\` if the buyer didn't provide a phone number or the store doesn't collect phone numbers. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * provinceCode The province, state, prefecture, or region code of the address. The format varies by country. The value is \`undefined\` if the buyer hasn't selected one yet or the country doesn't have provinces. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * zip The postal code or ZIP code of the address, used for mail sorting and delivery routing. The value is \`undefined\` if the buyer hasn't entered one yet or the country doesn't use postal codes. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` ## CheckoutApi The API object provided to `purchase.checkout` extension targets. * **applyShippingAddressChange** **(change: ShippingAddressUpdateChange) => Promise\** Updates the buyer's shipping address on the checkout. The provided fields are merged into the existing address without prompting the buyer. On success, the `shippingAddress` property updates to reflect the change. **Note:** This method returns an error if the \cart instruction\ \\delivery.can\Select\Custom\Address\\ is false, or the buyer is using an accelerated checkout method, such as Apple Pay or Google Pay. [](https://shopify.dev/apps/store/data-protection/protected-customer-data)Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### ShippingAddressUpdateChange Updates the buyer's shipping address on the checkout. Pass this to \`applyShippingAddressChange()\` to modify specific address fields without replacing the entire address. * address Fields to update in the shipping address. You only need to provide values for the fields you want to update. Any fields you don't list keep their current values. ```ts Partial ``` * type Identifies this as a shipping address update. This is the only supported change type for \`applyShippingAddressChange()\`. ```ts 'updateShippingAddress' ``` ### ShippingAddressChangeResult The result of calling \`applyShippingAddressChange()\`. Use the \`type\` property to determine whether the change succeeded or failed. On failure, the \`errors\` array contains field-level details. ```ts ShippingAddressChangeResultSuccess | ShippingAddressChangeResultError ``` ### ShippingAddressChangeResultSuccess The result of a successful shipping address change. The \`type\` property is \`'success'\` and \`errors\` is \`null\`. * errors Always \`null\` for a successful address change. Present so that you can check \`result.errors\` without narrowing the union type first. ```ts null ``` * type Indicates that the shipping address change was applied successfully. ```ts 'success' ``` ### ShippingAddressChangeResultError The result of a failed shipping address change. Check the \`errors\` array for field-level details about what went wrong. * errors The list of field-level errors that prevented the address change. Each entry identifies which address field failed and why. ```ts ShippingAddressChangeFieldError[] ``` * type Indicates that the shipping address change couldn't be applied. Check the \`errors\` array for field-level details. ```ts 'error' ``` ### ShippingAddressChangeFieldError An error corresponding to a particular field from a given change. Use the \`field\` property to determine which address field caused the error. * field The \`MailingAddress\` field that caused the error, such as \`'countryCode'\` or \`'zip'\`. The value is \`undefined\` if the error isn't specific to a single field. ```ts keyof MailingAddress ``` * message A message that explains the error. This message is useful for debugging. It isn't localized and shouldn't be displayed to the buyer. ```ts string ``` ## use​Billing​Address() Returns the proposed `billingAddress` applied to the checkout. ### Returns * **MailingAddress | undefined** ## use​Shipping​Address() Returns the proposed `shippingAddress` applied to the checkout. ### Returns * **ShippingAddress | undefined** ## use​Apply​Shipping​Address​Change() Returns a function to mutate the `shippingAddress` property of checkout. ### Returns * **(change: ShippingAddressChange) => Promise\ | undefined** ### ShippingAddressChange The input for \`applyShippingAddressChange()\`. Currently only supports \`ShippingAddressUpdateChange\` (with \`type: 'updateShippingAddress'\`). * address Fields to update in the shipping address. You only need to provide values for the fields you want to update. Any fields you don't list keep their current values. ```ts Partial ``` * type Identifies this as a shipping address update. This is the only supported change type for \`applyShippingAddressChange()\`. ```ts 'updateShippingAddress' ``` ## Related [Reference - Targets](https://shopify.dev/docs/api/checkout-ui-extensions/targets) [Reference - Components](https://shopify.dev/docs/api/checkout-ui-extensions/components) [Reference - Configuration](https://shopify.dev/docs/api/checkout-ui-extensions/configuration) [Learn - Tutorials](https://shopify.dev/apps/checkout)