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

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.

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

Anchor to buyerIdentity buyerIdentity: 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.
```
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.
```
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.
```
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.
```
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.
```
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.
```
() => 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.
```
(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.
```
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.
```
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.
```
string
```
firstName
The customer's first name. The value is `undefined` if the app doesn't have the required access level.
```
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.
```
string
```
id
A globally-unique identifier for the customer in the format `gid://shopify/Customer/<id>`. 'gid://shopify/Customer/123'
```
string
```
image
The customer's profile image, such as a Gravatar avatar. Use this to personalize the extension UI for the logged-in buyer.
```
ImageDetails
```
lastName
The customer's last name. The value is `undefined` if the app doesn't have the required access level.
```
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.
```
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.
```
StoreCreditAccount[]
```

ImageDetails

altText
The alternative text for the image, used for accessibility. The value is `undefined` if the merchant hasn't provided alt text.
```
string
```
url
The fully-qualified URL of the image. Use this to render the product or variant image in your extension.
```
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.
```
OrderStatusCompany
```
location
The specific company location where the order is being placed, including the location ID, name, and optional external ID.
```
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.
```
string
```
id
A globally-unique identifier for the company in the format `gid://shopify/Company/<id>`.
```
string
```
name
The registered business name of the company, as configured by the merchant in Shopify admin.
```
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.
```
string
```
id
A globally-unique identifier for the company location in the format `gid://shopify/CompanyLocation/<id>`.
```
string
```
name
The display name of the company location, such as a branch office or warehouse name.
```
string
```

Examples

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>

);

}

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

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

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

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

Was this page helpful?