---
title: Buyer Identity API
description: >-
  The Buyer Identity API provides read-only access to the buyer who placed the
  order on the Order status page, including their customer account, email,
  phone, and B2B purchasing company. Use this API to display buyer details,
  differentiate between B2B and direct-to-consumer orders, or detect guest
  buyers.
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/buyer-identity-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/latest/target-apis/order-apis/buyer-identity-api.md
---

# 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 read-only access to the buyer who placed the order on the [Order status page](https://shopify.dev/docs/api/customer-account-ui-extensions/latest/targets/order-status), including their customer account, email, phone, and B2B purchasing company. Use this API to display buyer details, differentiate between B2B and direct-to-consumer orders, or detect guest buyers.

Customer data reflects the account at the time the order was placed. If the buyer's account details have changed since then, the values returned by this API may not reflect those updates.

### 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/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 buyer identity. Access the following property on `shopify` to read information about the buyer who placed the order.

* **buyerIdentity**

  **OrderStatusBuyerIdentity**

  The buyer who placed the order, including their customer account, email, phone number, and B2B purchasing company. Use this to personalize the **Order status** page or identify B2B orders.

  Reflects the customer account at the time the order was placed. Doesn't update if account details change afterward.

### OrderStatusBuyerIdentity

Information about the buyer who placed the order. {% 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, including their ID and whether they have accepted marketing. The value is \`undefined\` if the buyer is a guest or hasn't logged in yet.

  ```ts
  SubscribableSignalLike<OrderStatusCustomer | undefined>
  ```

* email

  The email address associated with the order. This is the email the buyer provided during checkout for order confirmation and communication. The value is \`undefined\` if the app doesn't have access to customer data.

  ```ts
  SubscribableSignalLike<string | undefined>
  ```

* phone

  The phone number the buyer provided during checkout. The value is \`undefined\` if no phone number was provided or the app doesn't have access to customer data.

  ```ts
  SubscribableSignalLike<string | undefined>
  ```

* purchasingCompany

  The company and company location that a B2B (business-to-business) customer is purchasing on behalf of. Use this to identify the business context of the order. The value is \`undefined\` if the buyer isn't a B2B customer.

  ```ts
  SubscribableSignalLike<
      OrderStatusPurchasingCompany | undefined
    >
  ```

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

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

### OrderStatusCustomer

Information about a customer who has previously purchased from this shop. {% 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 receiving marketing communications from the merchant, such as email campaigns and promotional offers.

  ```ts
  boolean
  ```

* email

  The email address associated with the customer's account. The value is \`undefined\` if the app doesn't have the required access level.

  ```ts
  string
  ```

* firstName

  The customer's first name. The value is \`undefined\` if the app doesn't have the required access level.

  ```ts
  string
  ```

* fullName

  The customer's full name, typically a combination of first and last name. The value is \`undefined\` if the app doesn't have the required access level.

  ```ts
  string
  ```

* id

  A globally-unique identifier for the customer in the format \`gid://shopify/Customer/\<id>\`. 'gid://shopify/Customer/123'

  ```ts
  string
  ```

* image

  The customer's profile image, such as a Gravatar avatar. Use this to personalize the extension UI for the logged-in buyer.

  ```ts
  ImageDetails
  ```

* lastName

  The customer's last name. The value is \`undefined\` if the app doesn't have the required access level.

  ```ts
  string
  ```

* phone

  The phone number associated with the customer's account. The value is \`undefined\` if no phone number is on file or the app doesn't have the required access level.

  ```ts
  string
  ```

* storeCreditAccounts

  The store credit accounts owned by this customer that can be used as payment during checkout. Each account has a balance representing available store credit.

  ```ts
  StoreCreditAccount[]
  ```

### ImageDetails

* altText

  The alternative text for the image, used for accessibility. The value is \`undefined\` if the merchant hasn't provided alt text.

  ```ts
  string
  ```

* url

  The fully-qualified URL of the image. Use this to render the product or variant image in your extension.

  ```ts
  string
  ```

### OrderStatusPurchasingCompany

Information about a company 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 is purchasing on behalf of, including the company ID, name, and optional external ID.

  ```ts
  OrderStatusCompany
  ```

* location

  The specific company location where the order is being placed, including the location ID, name, and optional external ID.

  ```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 merchant-defined external identifier for the company, often used to map to an ID in an external ERP or CRM system. The value is \`undefined\` if no external ID has been set.

  ```ts
  string
  ```

* id

  A globally-unique identifier for the company in the format \`gid://shopify/Company/\<id>\`.

  ```ts
  string
  ```

* name

  The registered business name of the company, as configured by the merchant in Shopify admin.

  ```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 merchant-defined external identifier for the company location, often used to map to an ID in an external ERP or CRM system. The value is \`undefined\` if no external ID has been set.

  ```ts
  string
  ```

* id

  A globally-unique identifier for the company location in the format \`gid://shopify/CompanyLocation/\<id>\`.

  ```ts
  string
  ```

* name

  The display name of the company location, such as a branch office or warehouse name.

  ```ts
  string
  ```

Examples

### Examples

* ####

  ##### Description

  Show the buyer's email and phone number alongside their order information. This example reads \`shopify.buyerIdentity\` and renders the \`email\` and \`phone\` fields.

  ##### jsx

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    const buyerIdentity =
      shopify.buyerIdentity;
    const email = buyerIdentity.email?.value;
    const phone = buyerIdentity.phone?.value;

    return (
      <s-box padding="base">
        <s-stack direction="block" gap="small-200">
          <s-text type="strong">
            Contact Information
          </s-text>
          {email && (
            <s-text>Email: {email}</s-text>
          )}
          {phone && (
            <s-text>Phone: {phone}</s-text>
          )}
        </s-stack>
      </s-box>
    );
  }
  ```

* ####

  ##### Description

  Identify B2B orders and display company-specific information. This example checks whether \`shopify.buyerIdentity.purchasingCompany\` is defined and shows the company name and location.

  ##### jsx

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    const purchasingCompany =
      shopify.buyerIdentity?.purchasingCompany?.value;

    if (!purchasingCompany) {
      return null;
    }

    const {company, location} = purchasingCompany;

    return (
      <s-box padding="base">
        <s-stack direction="block" gap="small-200">
          <s-text type="strong">
            Business Order
          </s-text>
          <s-text>Company: {company.name}</s-text>
          <s-text>Location: {location.name}</s-text>
          <s-text color="subdued">
            This order was placed through a B2B
            account.
          </s-text>
        </s-stack>
      </s-box>
    );
  }
  ```

* ####

  ##### Description

  Determine if the buyer has a customer account or checked out as a guest. This example checks whether the \`customer\` property is defined on \`shopify.buyerIdentity\` and displays the appropriate message.

  ##### jsx

  ```jsx
  import '@shopify/ui-extensions/preact';
  import {render} from 'preact';

  export default async () => {
    render(<Extension />, document.body);
  };

  function Extension() {
    const customer =
      shopify.buyerIdentity?.customer?.value;
    const email = shopify.buyerIdentity?.email?.value;

    if (customer) {
      return (
        <s-box padding="base">
          <s-stack direction="block" gap="small-200">
            <s-text type="strong">
              Registered Customer
            </s-text>
            <s-text>
              Thank you for being a member! Check
              your account for exclusive offers.
            </s-text>
          </s-stack>
        </s-box>
      );
    }

    return (
      <s-box padding="base">
        <s-stack direction="block" gap="small-200">
          <s-text type="strong">
            Guest Checkout
          </s-text>
          <s-text>
            Order confirmation sent to {email}.
            Create an account to track future orders.
          </s-text>
        </s-stack>
      </s-box>
    );
  }
  ```

***