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:

Buyer Identity API

Requires access to protected customer data. The customer and purchasingCompany properties require level 1 access. The email and phone properties require level 2 access.

The Buyer Identity API provides information about the buyer who placed the order, including their customer account, email, phone, and B2B company details. Use it to display buyer information or personalize the Order status page experience.

Anchor to Use casesUse cases

Display buyer details: Show the buyer's email or phone number alongside their order information.
Identify B2B orders: Detect B2B orders and display company-specific information such as the company name or location.
Guest vs. signed-in detection: Determine if the buyer has a customer account or is checking out as a guest.

Support

Targets (10)

Supported targets

Anchor to PropertiesProperties

The Buyer Identity API object provides buyer identity information from the order. Access the following properties on the API object to read buyer data.

Anchor to buyerIdentity buyerIdentity: Information about the buyer who placed the order, including their customer account, email, phone, and B2B company details.

OrderStatusBuyerIdentity

{% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data). The `customer` and `purchasingCompany` properties require level 1 access. The `email` and `phone` properties require level 2 access.

customer
The buyer's customer account. The value is undefined if the buyer isn’t a known customer for this shop or if they haven't logged in yet.
```
StatefulRemoteSubscribable<OrderStatusCustomer | undefined>
```
email
The buyer's email address associated with the order. The value is `undefined` if the app doesn't have access to customer data.
```
StatefulRemoteSubscribable<string | undefined>
```
phone
The buyer's phone number associated with the order. The value is `undefined` if the app doesn't have access to customer data.
```
StatefulRemoteSubscribable<string | undefined>
```
purchasingCompany
The company and company location that the B2B customer is purchasing on behalf of. The value is `undefined` if the buyer isn't a B2B customer.
```
StatefulRemoteSubscribable<
    OrderStatusPurchasingCompany | undefined
  >
```

OrderStatusCustomer

The customer associated with the order. {% include /apps/checkout/privacy-icon.md %} Requires access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data). The `id`, `image`, `acceptsMarketing`, and `storeCreditAccounts` properties require level 1 access. The `email`, `phone`, `fullName`, `firstName`, and `lastName` properties require level 2 access.

acceptsMarketing
Whether the customer has opted in to receive marketing communications from the merchant.
```
boolean
```
email
The customer's email address.
```
string
```
firstName
The customer's first name.
```
string
```
fullName
The customer's full name, combining first and last name.
```
string
```
id
A globally-unique identifier for the customer.
```
string
```
image
The customer's profile image, such as a Gravatar.
```
ImageDetails
```
lastName
The customer's last name.
```
string
```
phone
The customer's phone number.
```
string
```
storeCreditAccounts
The store credit accounts owned by the customer that can be applied during checkout.
```
StoreCreditAccount[]
```

ImageDetails

altText
The alternative text for the image, used for accessibility and displayed when the image can't be loaded.
```
string
```
url
The fully-qualified URL of the image.
```
string
```

OrderStatusPurchasingCompany

The B2B company and location that the business customer is purchasing on behalf of. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

company
The company that the B2B customer belongs to.
```
OrderStatusCompany
```
location
The company location that the B2B customer is purchasing for.
```
OrderStatusCompanyLocation
```

OrderStatusCompany

{% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

externalId
A custom external identifier for the company, set by the merchant. Useful for syncing with external systems.
```
string
```
id
A globally-unique identifier for the company.
```
string
```
name
The display name of the company.
```
string
```

OrderStatusCompanyLocation

{% include /apps/checkout/privacy-icon.md %} Requires level 1 access to [protected customer data](/docs/apps/store/data-protection/protected-customer-data).

externalId
A custom external identifier for the company location, set by the merchant. Useful for syncing with external systems.
```
string
```
id
A globally-unique identifier for the company location.
```
string
```
name
The display name of the company location.
```
string
```

Examples

import {

reactExtension,

useCustomer,

} 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 customer = useCustomer();

if (!customer) return <Text>Guest checkout</Text>;

return (

<Text emphasis="bold">Customer</Text>

{customer.fullName && <Text>{customer.fullName}</Text>}

{customer.email && <Text appearance="subdued">{customer.email}</Text>}

</BlockStack>

);

}

Examples

Description

Read the buyer's customer information and display their name and email. This example uses the `useCustomer` hook and handles the case where the customer isn't signed in.

React

import {
  reactExtension,
  useCustomer,
} 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 customer = useCustomer();
  if (!customer) return <Text>Guest checkout</Text>;
  return (
    <BlockStack>
      <Text emphasis="bold">Customer</Text>
      {customer.fullName && <Text>{customer.fullName}</Text>}
      {customer.email && <Text appearance="subdued">{customer.email}</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 customer = api.buyerIdentity?.customer.current;
    if (!customer) {
      root.appendChild(root.createComponent(Text, {}, 'Guest checkout'));
      return;
    }
    const stack = root.createComponent(BlockStack, {});
    stack.appendChild(root.createComponent(Text, {emphasis: 'bold'}, 'Customer'));
    if (customer.fullName) stack.appendChild(root.createComponent(Text, {}, customer.fullName));
    if (customer.email) stack.appendChild(root.createComponent(Text, {appearance: 'subdued'}, customer.email));
    root.appendChild(stack);
  },
);

Description

Read the buyer's first name and display a personalized greeting. This example uses `useCustomer` and falls back to a generic message when the name isn't available.

React

import {
  reactExtension,
  useCustomer,
} 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 customer = useCustomer();
  if (!customer?.firstName) return null;
  return (
    <Banner status="info">
      <Text>Thanks for your order, {customer.firstName}!</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 customer = api.buyerIdentity?.customer.current;
    if (!customer?.firstName) return;
    const banner = root.createComponent(Banner, {status: 'info'});
    banner.appendChild(root.createComponent(Text, {}, `Thanks for your order, ${customer.firstName}!`));
    root.appendChild(banner);
  },
);

Description

Read the purchasing company and display B2B company details. This example uses `usePurchasingCompany` and only renders company information when the buyer is a B2B customer.

React

import {
  reactExtension,
  usePurchasingCompany,
} 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 purchasingCompany = usePurchasingCompany();
  if (!purchasingCompany) return null;
  return (
    <BlockStack>
      <Text emphasis="bold">B2B order</Text>
      <Text>Company: {purchasingCompany.company.name}</Text>
      {purchasingCompany.location && (
        <Text>Location: {purchasingCompany.location.name}</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 purchasingCompany = api.buyerIdentity?.purchasingCompany.current;
    if (!purchasingCompany) return;
    const stack = root.createComponent(BlockStack, {});
    stack.appendChild(root.createComponent(Text, {emphasis: 'bold'}, 'B2B order'));
    stack.appendChild(root.createComponent(Text, {}, `Company: ${purchasingCompany.company.name}`));
    if (purchasingCompany.location) {
      stack.appendChild(root.createComponent(Text, {}, `Location: ${purchasingCompany.location.name}`));
    }
    root.appendChild(stack);
  },
);

Anchor to Best practicesBest practices

Check for undefined customer: The customer property is undefined when the buyer isn't signed in. Always verify the customer exists before accessing their details.
Handle B2B customers separately: Use usePurchasingCompany to detect B2B orders and display company-specific information like the company name and location.

Anchor to LimitationsLimitations

The customer property represents the customer account at the time the order was placed. If the buyer's account details (such as email or name) have changed since then, the data returned may not reflect those updates.

Was this page helpful?