--- title: Addresses API description: >- The Addresses API provides read-only access to the shipping and billing addresses associated with an order on the Order status page. Use this API to read structured MailingAddress data, including recipient names, street addresses, and country details. api_version: 2026-04 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/addresses-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/addresses-api.md --- # Addresses API **Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). Most properties require level 2 access. The \`company\` property requires level 1 access.:** The Addresses API provides read-only access to the shipping and billing addresses associated with an order on the [Order status page](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status). Use this API to read structured `MailingAddress` data, including recipient names, street addresses, and country details. Address data reflects the state at the time the order was placed. If the customer updates their address in their account after placing the order, the values returned by this API don't change. ### Use cases * **Display shipping details**: Show the shipping address associated with the order, such as the recipient name, street address, city, and country. * **Display billing details**: Show the billing address used for the order's payment. * **Address comparison**: Compare the shipping and billing addresses to determine if they differ, and display a summary to the buyer. ### Support Targets (10) ### Supported targets * [customer-account.​order-status.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-item-render-after-) * [customer-account.​order-status.​cart-line-list.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#cart-line-list-render-after-) * [customer-account.​order-status.​customer-information.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#payments-and-returns-targets) * [customer-account.​order-status.​return-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/payments-and-returns#return-details-render-after-) * [customer-account.​order-status.​unfulfilled-items.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2026-04/targets/full-page#order-specific-full-page-) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/latest#target-apis-define-what-your-extension-does) provides the shipping and billing addresses associated with the order. Access the following properties on `shopify` to read the mailing addresses that were used for the order. * **billingAddress** **SubscribableSignalLike\** The billing address associated with the buyer's payment method for the order. The value is `undefined` if the order doesn't have a billing address on file. Reflects the state at the time the order was placed. Doesn't update if the customer changes their account address afterward. * **shippingAddress** **SubscribableSignalLike\** The shipping address that the buyer provided for the order. This is where physical goods are delivered. The value is `undefined` if the order contains only digital products or if a shipping address wasn't required. Reflects the state at the time the order was placed. Doesn't update if the customer changes their account address afterward. ### 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' ``` Examples ### Examples * #### ##### Description Display the shipping address for an order, including the recipient name, street address, city, and country. This example reads \`shopify.shippingAddress\` and handles the case where the address is \`undefined\` for digital-only orders. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const address = shopify.shippingAddress?.value; if (!address) { return ( No shipping address on file for this order. ); } return ( {address.name} {address.address1} {address.address2 && ( {address.address2} )} {address.city}, {address.provinceCode}{' '} {address.zip} {address.countryCode} ); } ``` * #### ##### Description Compare the shipping and billing addresses to determine whether they match. This example reads both \`shopify.shippingAddress\` and \`shopify.billingAddress\`, checks key fields like \`address1\`, \`city\`, and \`zip\`, and displays a banner indicating whether the addresses are the same or different. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const shipping = shopify.shippingAddress?.value; const billing = shopify.billingAddress?.value; if (!shipping || !billing) { return null; } const isSameAddress = shipping.address1 === billing.address1 && shipping.city === billing.city && shipping.zip === billing.zip && shipping.countryCode === billing.countryCode; return ( {isSameAddress ? 'Shipping and billing addresses match.' : 'Shipping and billing addresses are different. Please verify your billing details.'} ); } ``` * #### ##### Description Display the billing address associated with the buyer's payment method. This example reads \`shopify.billingAddress\` and gracefully handles digital-only orders where the billing address may be \`undefined\`. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const address = shopify.billingAddress?.value; if (!address) { return ( No billing address required for digital orders. ); } return ( Billing address {address.name} {address.address1} {address.address2 && ( {address.address2} )} {address.city}, {address.provinceCode}{' '} {address.zip} {address.countryCode} ); } ``` *** ## Best practices * **Handle digital-only orders**: Orders that contain only digital products may not have a shipping address. Check for `undefined` before rendering any shipping-related UI. ***