---
title: Buyer Identity API
description: >-
  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.
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/buyer-identity-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/order-apis/buyer-identity-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.

# Buyer Identity API

**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.:**

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.

### Use 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

* [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 Buyer Identity API object provides buyer identity information from the order. Access the following properties on the API object to read buyer data.

* **buyerIdentity**

  **OrderStatusBuyerIdentity**

  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.

  ```ts
  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.

  ```ts
  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.

  ```ts
  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.

  ```ts
  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.

  ```ts
  boolean
  ```

* email

  The customer's email address.

  ```ts
  string
  ```

* firstName

  The customer's first name.

  ```ts
  string
  ```

* fullName

  The customer's full name, combining first and last name.

  ```ts
  string
  ```

* id

  A globally-unique identifier for the customer.

  ```ts
  string
  ```

* image

  The customer's profile image, such as a Gravatar.

  ```ts
  ImageDetails
  ```

* lastName

  The customer's last name.

  ```ts
  string
  ```

* phone

  The customer's phone number.

  ```ts
  string
  ```

* storeCreditAccounts

  The store credit accounts owned by the customer that can be applied during checkout.

  ```ts
  StoreCreditAccount[]
  ```

### ImageDetails

* altText

  The alternative text for the image, used for accessibility and displayed when the image can't be loaded.

  ```ts
  string
  ```

* url

  The fully-qualified URL of the image.

  ```ts
  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.

  ```ts
  OrderStatusCompany
  ```

* location

  The company location that the B2B customer is purchasing for.

  ```ts
  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.

  ```ts
  string
  ```

* id

  A globally-unique identifier for the company.

  ```ts
  string
  ```

* name

  The display name of the company.

  ```ts
  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.

  ```ts
  string
  ```

* id

  A globally-unique identifier for the company location.

  ```ts
  string
  ```

* name

  The display name of the company location.

  ```ts
  string
  ```

Examples

### 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

  ```tsx
  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

  ```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

  ```tsx
  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

  ```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

  ```tsx
  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

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

***

## Best 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.

***

## Limitations

* 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.

***