Migrate to Polaris

Version 2025-07 is the last API version to support React-based UI components. Later versions use web components, native UI elements with built-in accessibility, better performance, and consistent styling with Shopify's design system. Check out the migration guide to upgrade your extension.

Choose a version:

Addresses API

Requires access to 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.

Anchor to Use casesUse 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

Anchor to PropertiesProperties

The Addresses API object provides the buyer's shipping and billing addresses. Access the following properties on the API object to read address data.

Anchor to billingAddress billingAddress StatefulRemoteSubscribable< | undefined>: The billing address associated with the buyer's payment method.
Anchor to shippingAddress shippingAddress StatefulRemoteSubscribable< | undefined>: 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.
```
string
```
address2
The second line of the street address, such as apartment number, suite, or unit.
```
string
```
city
The city, town, or village name.
```
string
```
company
The company or organization name associated with the address.
```
string
```
countryCode
The [ISO 3166-1 Alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code.
```
CountryCode
```
firstName
The buyer's given name.
```
string
```
lastName
The buyer's family name.
```
string
```
name
The buyer's full name, typically the first and last name combined.
```
string
```
phone
The phone number associated with the address.
```
string
```
provinceCode
The buyer's province, state, or region code.
```
string
```
zip
The postal code or ZIP code.
```
string
```

CountryCode

'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

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',

() => <Extension />,

);

function Extension() {

const address = useShippingAddress();

if (!address) {

return <Text>No shipping address available.</Text>;

}

return (

<Text emphasis="bold">Shipping address</Text>

{address.name && <Text>{address.name}</Text>}

{address.address1 && <Text>{address.address1}</Text>}

{address.address2 && <Text>{address.address2}</Text>}

<Text>

{[address.city, address.provinceCode, address.zip]

.filter(Boolean)

.join(', ')}

</Text>

{address.countryCode && <Text>{address.countryCode}</Text>}

</BlockStack>

);

}

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

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',
  () => <Extension />,
);

function Extension() {
  const address = useShippingAddress();

  if (!address) {
    return <Text>No shipping address available.</Text>;
  }

  return (
    <BlockStack>
      <Text emphasis="bold">Shipping address</Text>
      {address.name && <Text>{address.name}</Text>}
      {address.address1 && <Text>{address.address1}</Text>}
      {address.address2 && <Text>{address.address2}</Text>}
      <Text>
        {[address.city, address.provinceCode, address.zip]
          .filter(Boolean)
          .join(', ')}
      </Text>
      {address.countryCode && <Text>{address.countryCode}</Text>}
    </BlockStack>
  );
}

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

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',
  () => <Extension />,
);

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 (
    <Banner
      status={isSameAddress ? 'info' : 'warning'}
    >
      <Text>
        {isSameAddress
          ? 'Shipping and billing addresses match.'
          : 'Shipping and billing addresses are different.'}
      </Text>
    </Banner>
  );
}

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

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',
  () => <Extension />,
);

function Extension() {
  const address = useBillingAddress();

  if (!address) {
    return <Text>No billing address available.</Text>;
  }

  return (
    <BlockStack>
      <Text emphasis="bold">Billing address</Text>
      {address.name && <Text>{address.name}</Text>}
      {address.address1 && <Text>{address.address1}</Text>}
      <Text>
        {[address.city, address.provinceCode, address.zip]
          .filter(Boolean)
          .join(', ')}
      </Text>
    </BlockStack>
  );
}

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);
  },
);

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

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.

Was this page helpful?