--- title: Addresses API description: >- The Addresses API provides the buyer's shipping and billing addresses from the order. Use it to display address details or compare shipping and billing information on the Order status page. api_version: 2025-07 api_name: customer-account-ui-extensions source_url: html: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/addresses-api md: >- https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/addresses-api.md --- Migrate to Polaris Version 2025-07 is the last API version to support React-based UI components. Later versions use [web components](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/polaris-web-components), native UI elements with built-in accessibility, better performance, and consistent styling with [Shopify's design system](https://shopify.dev/docs/apps/design). Check out the [migration guide](https://shopify.dev/docs/apps/build/customer-accounts/migrate-to-web-components) to upgrade your extension. # 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 the buyer's shipping and billing addresses from the order. Use it to display address details or compare shipping and billing information on the Order status page. ### 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/2025-07/targets/order-status#order-status-announcement-) * [customer-account.​order-status.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-status#order-status-block-) * [customer-account.​order-status.​cart-line-item.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/order-status#customer-information-render-after-) * [customer-account.​order-status.​fulfillment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/fulfillment-status#fulfillment-status-targets) * [customer-account.​order-status.​payment-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/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/2025-07/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/2025-07/targets/fulfillment-status#unfulfilled-items-render-after-) * [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-) ### Properties The Addresses API object provides the buyer's shipping and billing addresses. Access the following properties on the API object to read address data. * **billingAddress** **StatefulRemoteSubscribable\** The billing address associated with the buyer's payment method. * **shippingAddress** **StatefulRemoteSubscribable\** The shipping address that the buyer provided for the order. ### MailingAddress {% include /apps/checkout/privacy-icon.md %} 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. * address1 The first line of the street address, including the street number and name. ```ts string ``` * address2 The second line of the street address, such as apartment number, suite, or unit. ```ts string ``` * city The city, town, or village name. ```ts string ``` * company The company or organization name associated with the address. ```ts string ``` * countryCode The \[ISO 3166-1 Alpha-2]\(https://www\.iso.org/iso-3166-country-codes.html) country code. ```ts CountryCode ``` * firstName The buyer's given name. ```ts string ``` * lastName The buyer's family name. ```ts string ``` * name The buyer's full name, typically the first and last name combined. ```ts string ``` * phone The phone number associated with the address. ```ts string ``` * provinceCode The buyer's province, state, or region code. ```ts string ``` * zip The postal code or ZIP code. ```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 Read the shipping address from the order and render each address field in a formatted block. This example uses the \`useShippingAddress\` hook and handles the case where the address is \`undefined\` for digital orders. ##### React ```tsx import { reactExtension, useShippingAddress, } from '@shopify/ui-extensions-react/customer-account'; import { BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const address = useShippingAddress(); if (!address) { return No shipping address available.; } return ( Shipping address {address.name && {address.name}} {address.address1 && {address.address1}} {address.address2 && {address.address2}} {[address.city, address.provinceCode, address.zip] .filter(Boolean) .join(', ')} {address.countryCode && {address.countryCode}} ); } ``` ##### TS ```ts import { extension, BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, api) => { const address = api.shippingAddress?.current; if (!address) { root.appendChild( root.createComponent(Text, {}, 'No shipping address available.'), ); return; } const stack = root.createComponent(BlockStack, {}); stack.appendChild( root.createComponent(Text, {emphasis: 'bold'}, 'Shipping address'), ); if (address.name) { stack.appendChild(root.createComponent(Text, {}, address.name)); } if (address.address1) { stack.appendChild(root.createComponent(Text, {}, address.address1)); } const cityLine = [address.city, address.provinceCode, address.zip] .filter(Boolean) .join(', '); stack.appendChild(root.createComponent(Text, {}, cityLine)); root.appendChild(stack); }, ); ``` * #### ##### Description Compare the shipping and billing addresses to determine if they match, and display a status banner. This example uses both \`useShippingAddress\` and \`useBillingAddress\` to check key fields like \`address1\`, \`city\`, and \`zip\`. ##### React ```tsx import { reactExtension, useShippingAddress, useBillingAddress, } from '@shopify/ui-extensions-react/customer-account'; import { Banner, Text, } from '@shopify/ui-extensions/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const shipping = useShippingAddress(); const billing = useBillingAddress(); 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.'} ); } ``` ##### TS ```ts import { extension, Banner, Text, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, api) => { const shipping = api.shippingAddress?.current; const billing = api.billingAddress?.current; if (!shipping || !billing) return; const isSameAddress = shipping.address1 === billing.address1 && shipping.city === billing.city && shipping.zip === billing.zip && shipping.countryCode === billing.countryCode; const banner = root.createComponent( Banner, {status: isSameAddress ? 'info' : 'warning'}, ); banner.appendChild( root.createComponent( Text, {}, isSameAddress ? 'Shipping and billing addresses match.' : 'Shipping and billing addresses are different.', ), ); root.appendChild(banner); }, ); ``` * #### ##### Description Read the billing address from the order and render each field in a formatted block. This example uses the \`useBillingAddress\` hook and gracefully handles \`undefined\` values for optional fields. ##### React ```tsx import { reactExtension, useBillingAddress, } from '@shopify/ui-extensions-react/customer-account'; import { BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default reactExtension( 'customer-account.order-status.block.render', () => , ); function Extension() { const address = useBillingAddress(); if (!address) { return No billing address available.; } return ( Billing address {address.name && {address.name}} {address.address1 && {address.address1}} {[address.city, address.provinceCode, address.zip] .filter(Boolean) .join(', ')} ); } ``` ##### TS ```ts import { extension, BlockStack, Text, } from '@shopify/ui-extensions/customer-account'; export default extension( 'customer-account.order-status.block.render', (root, api) => { const address = api.billingAddress?.current; if (!address) { root.appendChild( root.createComponent(Text, {}, 'No billing address available.'), ); return; } const stack = root.createComponent(BlockStack, {}); stack.appendChild( root.createComponent(Text, {emphasis: 'bold'}, 'Billing address'), ); if (address.name) { stack.appendChild(root.createComponent(Text, {}, address.name)); } if (address.address1) { stack.appendChild(root.createComponent(Text, {}, address.address1)); } const cityLine = [address.city, address.provinceCode, address.zip] .filter(Boolean) .join(', '); stack.appendChild(root.createComponent(Text, {}, cityLine)); root.appendChild(stack); }, ); ``` *** ## Best practices * **Gracefully handle missing addresses**: Either the shipping or billing address may be `undefined`. Always check for `undefined` before rendering address fields. * **Don't assume address completeness**: Some fields like `address2`, `company`, and `phone` are optional and may not be present. *** ## Limitations * Addresses reflect the state at the time of checkout. If the customer updates their address in their account after placing the order, the values returned by this API don't change. ***