--- title: Buyer Identity API description: >- The Buyer Identity API provides access to the buyer's identity information during checkout, including customer details and B2B purchasing company data. Use this API to identify returning customers, personalize the checkout experience, and detect B2B sessions. api_version: 2026-04 api_name: checkout-ui-extensions source_url: html: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/buyer-identity-api md: >- https://shopify.dev/docs/api/checkout-ui-extensions/latest/target-apis/checkout-apis/buyer-identity-api.md --- # Buyer Identity API **Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data).:** The Buyer Identity API provides access to the buyer's identity information during checkout, including customer details and B2B purchasing company data. Use this API to identify returning customers, personalize the checkout experience, and detect B2B sessions. The Buyer Identity API is read-only. There are no methods to update the buyer's identity from a checkout extension. The `customer` property is `undefined` when the buyer isn't a known customer or hasn't logged in. ### Use cases * **Display buyer details**: Greet returning buyers by name and show their contact information during checkout. * **Identify B2B sessions**: Determine if the buyer is purchasing on behalf of a company and display company-specific details. * **Personalize the checkout**: Use the buyer's email, phone, or customer ID to tailor the checkout experience. ### Support Targets (31) ### Supported targets * [purchase.​checkout.​actions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/navigation#navigation-target) * [purchase.​checkout.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/block#block-target) * [purchase.​checkout.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#line-item-targets) * [purchase.​checkout.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-cart-line-list-) * purchase.​checkout.​chat.​render * [purchase.​checkout.​contact.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/information#information-target) * [purchase.​checkout.​delivery-address.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-delivery-address-) * [purchase.​checkout.​delivery-address.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#delivery-address-targets) * [purchase.​checkout.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/footer#footer-target) * [purchase.​checkout.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/header#header-target) * [purchase.​checkout.​payment-method-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#render-after-payment-methods-) * [purchase.​checkout.​payment-method-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/payment#payment-targets) * [purchase.​checkout.​pickup-location-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#render-after-pickup-locations-) * [purchase.​checkout.​pickup-location-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-list-targets) * [purchase.​checkout.​pickup-location-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/local-pickup#location-option-item-target) * [purchase.​checkout.​pickup-point-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#render-after-pickup-points-) * [purchase.​checkout.​pickup-point-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/pickup-points#pickup-points-targets) * [purchase.​checkout.​reductions.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#checkout-reductions-after-) * [purchase.​checkout.​reductions.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/order-summary#reductions-targets) * [purchase.​checkout.​shipping-option-item.​details.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-item-targets) * [purchase.​checkout.​shipping-option-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-option-) * [purchase.​checkout.​shipping-option-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#render-after-shipping-options-) * [purchase.​checkout.​shipping-option-list.​render-before](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/checkout/shipping#shipping-option-list-targets) * [purchase.​thank-you.​announcement.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/announcement#thank-you-announcement-) * [purchase.​thank-you.​block.​render](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/block#block-target) * [purchase.​thank-you.​cart-line-item.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#line-item-targets) * [purchase.​thank-you.​cart-line-list.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/order-summary#thank-you-cart-line-list-) * purchase.​thank-you.​chat.​render * [purchase.​thank-you.​customer-information.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/information#information-target) * [purchase.​thank-you.​footer.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/footer#footer-target) * [purchase.​thank-you.​header.​render-after](https://shopify.dev/docs/api/checkout-ui-extensions/2026-04/targets/thank-you/header#header-target) ### Properties The [`shopify` global object](https://shopify.dev/docs/api/checkout-ui-extensions/latest#target-apis-define-what-your-extension-does) provides buyer identity data for the current checkout. Access the following properties on `shopify` to read customer details and B2B purchasing company information. Available to `purchase` extension targets. * **buyerIdentity** **BuyerIdentity** Information about the buyer that's interacting with the checkout. The property is available only if the extension has access to protected customer data. [](https://shopify.dev/apps/store/data-protection/protected-customer-data)Requires access to [protected customer data](https://shopify.dev/docs/apps/store/data-protection/protected-customer-data). ### BuyerIdentity Information about the buyer who is completing the checkout. {% 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've accepted marketing. The value is \`undefined\` if the buyer isn't a known customer for this shop or if they haven't logged in yet. {% include /apps/checkout/privacy-icon.md %} Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts SubscribableSignalLike ``` * email The email address the buyer provided during checkout. The value is \`undefined\` if the app doesn't have access to customer data. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts SubscribableSignalLike ``` * 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. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts SubscribableSignalLike ``` * 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. {% include /apps/checkout/privacy-icon.md %} Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts SubscribableSignalLike ``` ### 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 ``` * 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 ``` ### Customer 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). * acceptsEmailMarketing Whether the customer has opted in to email marketing. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts boolean ``` * acceptsMarketing Whether the customer has opted in to receiving marketing communications from the merchant, such as email campaigns and promotional offers. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). > Caution: This field is deprecated and will be removed in a future version. Use \`acceptsEmailMarketing\` or \`acceptsSmsMarketing\` instead. ```ts boolean ``` * acceptsSmsMarketing Whether the customer has opted in to SMS marketing. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```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. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * firstName The customer's first name. The value is \`undefined\` if the app doesn't have the required access level. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```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. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * id An identifier for the customer in the format \`gid://shopify/Customer/\\`. This value is unique per shop. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```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. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts ImageDetails ``` * lastName The customer's last name. The value is \`undefined\` if the app doesn't have the required access level. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * ordersCount The number of orders the customer has previously placed with this shop. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts number ``` * 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. {% include /apps/checkout/privacy-icon.md %} Requires level 2 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```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. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```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 ``` ### PurchasingCompany The company and location that the \[B2B]\(/docs/apps/build/b2b) customer is purchasing on behalf of. This is present only when the buyer is logged in as a business customer. * company The company the B2B customer belongs to. {% include /apps/checkout/privacy-icon.md %} Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts Company ``` * location The specific company location associated with this B2B purchase. {% include /apps/checkout/privacy-icon.md %} Requires access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts CompanyLocation ``` ### Company * externalId A merchant-defined external identifier for the company. The value is \`undefined\` if the merchant hasn't set one. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * id A globally-unique identifier for the company in the format \`gid://shopify/Company/\\`. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * name The company's display name. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` ### CompanyLocation * externalId A merchant-defined external identifier for the company location. The value is \`undefined\` if the merchant hasn't set one. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * id A globally-unique identifier for the company location in the format \`gid://shopify/CompanyLocation/\\`. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` * name The display name of the company location. {% include /apps/checkout/privacy-icon.md %} Requires level 1 access to \[protected customer data]\(/docs/apps/store/data-protection/protected-customer-data). ```ts string ``` Examples ### Examples * #### ##### Description Greet returning buyers with a personalized welcome banner. This example reads \`shopify.buyerIdentity.customer\` and displays the buyer's name and order count, with a fallback when \`fullName\` is unavailable. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const customer = shopify.buyerIdentity?.customer.value; if (!customer) { return null; } const name = customer.fullName ?? 'Customer'; return ( {name}, you have {customer.ordersCount}{' '} previous{' '} {customer.ordersCount === 1 ? 'order' : 'orders'}{' '} with us. ); } ``` * #### ##### Description Identify B2B buyers and show the purchasing company's name and location. This example checks whether \`shopify.buyerIdentity.purchasingCompany\` is defined and renders the details in a banner. ##### jsx ```jsx import '@shopify/ui-extensions/preact'; import {render} from 'preact'; export default function extension() { render(, document.body); } function Extension() { const purchasingCompany = shopify.buyerIdentity?.purchasingCompany.value; if (!purchasingCompany) { return null; } return ( Purchasing on behalf of{' '} {purchasingCompany.company.name},{' '} location:{' '} {purchasingCompany.location.name} ); } ``` *** ## Best practices * **For multi-shop apps, key records on shop and `customer.id` together**: `customer.id` is unique per shop. If your app is installed on multiple shops and keys records only on `customer.id`, then it can't reliably correlate a buyer across shops. * **Check marketing consent before using contact details**: The `Customer` object includes `acceptsEmailMarketing` and `acceptsSmsMarketing` flags. Respect these preferences when using the buyer's email or phone for marketing purposes. ***