---
title: Customer Account API
description: >-
  The Customer Account API lets your extension query the Customer Account
  GraphQL API using the global fetch(). Use it to fetch customer data like order
  history, addresses, and profile information from the Order status page.
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/account-apis/customer-account-api
  md: >-
    https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/target-apis/account-apis/customer-account-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.

# Customer Account API

The Customer Account API lets your extension query the Customer Account GraphQL API using the global `fetch()`. Use it to fetch customer data like order history, addresses, and profile information from the Order status page.

Unlike other target APIs that expose typed properties on the [`shopify` global object](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07#target-apis-define-what-your-extension-does), this API provides direct access to the full GraphQL schema through `fetch('shopify://customer-account/api/2025-07/graphql.json')`. Authentication is handled automatically, so you don't need a session token.

### Use cases

* **Fetch order history**: Query the customer's past orders to display a purchase history or recommend related products.
* **Access customer profile**: Retrieve the customer's name, email, and saved addresses for a personalized experience.
* **Write customer data**: Update customer records, create [metafields](https://shopify.dev/docs/apps/build/customer-accounts/metafields-in-customer-accounts), or modify order information directly through GraphQL mutations.

### Support Targets (25)

### Supported targets

* Customer​Account::Kitchen​Sink
* [customer-account.​footer.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/footer#footer-render-after-)
* [customer-account.​order-index.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-targets)
* [customer-account.​order-index.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-index#order-index-block-)
* [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.​action.​menu-item.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-menu-item-)
* [customer-account.​order.​action.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/order-actions#order-action-)
* [customer-account.​order.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#order-specific-full-page-)
* [customer-account.​page.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/full-page#customer-account-full-page-)
* [customer-account.​profile.​addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-page-default-targets-)
* [customer-account.​profile.​announcement.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#announcement-)
* [customer-account.​profile.​block.​render](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-default#profile-block-)
* [customer-account.​profile.​company-details.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#profile-page-b2b-targets-)
* [customer-account.​profile.​company-location-addresses.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-addresses-render-after-)
* [customer-account.​profile.​company-location-payment.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-payment-render-after-)
* [customer-account.​profile.​company-location-staff.​render-after](https://shopify.dev/docs/api/customer-account-ui-extensions/2025-07/targets/profile-page-b2b#company-location-staff-render-after-)
* customer-account.​profile.​payment.​render-after

Examples

### Examples

* ####

  ##### Description

  Fetch the customer's display name from the Customer Account API. This example sends a GraphQL query using \`fetch()\` with the \`shopify://\` protocol and render the result.

  ##### React

  ```tsx
  import React, {useEffect, useState} from 'react';
  import {reactExtension} from '@shopify/ui-extensions-react/customer-account';
  import {Banner, Text} from '@shopify/ui-extensions/customer-account';

  const API_VERSION = '2025-07';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const [customerName, setCustomerName] = useState('');

    useEffect(() => {
      fetch(`shopify://customer-account/api/${API_VERSION}/graphql.json`, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({query: `query { customer { firstName } }`}),
      })
        .then((res) => res.json())
        .then(({data}) => {
          if (!data.customer) return;
          setCustomerName(data.customer.firstName);
        })
        .catch(console.error);
    }, []);

    if (!customerName) return null;
    return (
      <Banner><Text>Welcome back, {customerName}!</Text></Banner>
    );
  }
  ```

  ##### TS

  ```ts
  import {extension, Banner, Text} from '@shopify/ui-extensions/customer-account';

  const API_VERSION = '2025-07';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      fetch(`shopify://customer-account/api/${API_VERSION}/graphql.json`, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({query: `query { customer { firstName } }`}),
      })
        .then((res) => res.json())
        .then(({data}) => {
          if (!data.customer) return;
          if (data.customer.firstName) {
            const banner = root.createComponent(Banner, {});
            banner.appendChild(root.createComponent(Text, {}, `Welcome back, ${data.customer.firstName}!`));
            root.appendChild(banner);
          }
        })
        .catch(console.error);
    },
  );
  ```

* ####

  ##### Description

  Count the customer's past orders using the Customer Account API. This example queries the \`orders\` connection and displays the total number of orders placed.

  ##### React

  ```tsx
  import React, {useEffect, useState} from 'react';
  import {reactExtension} from '@shopify/ui-extensions-react/customer-account';
  import {BlockStack, Text} from '@shopify/ui-extensions/customer-account';

  const API_VERSION = '2025-07';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const [orderCount, setOrderCount] = useState<number | null>(null);

    useEffect(() => {
      fetch(`shopify://customer-account/api/${API_VERSION}/graphql.json`, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          query: `query { customer { orders(first: 100) { nodes { id } } } }`,
        }),
      })
        .then((res) => res.json())
        .then(({data}) => {
          if (!data.customer) return;
          setOrderCount(data.customer.orders.nodes.length);
        })
        .catch(console.error);
    }, []);

    if (orderCount === null) return null;
    return (
      <BlockStack>
        <Text>You have placed {orderCount} order{orderCount !== 1 ? 's' : ''} with us.</Text>
      </BlockStack>
    );
  }
  ```

  ##### TS

  ```ts
  import {extension, BlockStack, Text} from '@shopify/ui-extensions/customer-account';

  const API_VERSION = '2025-07';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      fetch(`shopify://customer-account/api/${API_VERSION}/graphql.json`, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          query: `query { customer { orders(first: 100) { nodes { id } } } }`,
        }),
      })
        .then((res) => res.json())
        .then(({data}) => {
          if (!data.customer) return;
          const count = data.customer.orders.nodes.length;
          const stack = root.createComponent(BlockStack, {});
          stack.appendChild(
            root.createComponent(Text, {}, `You have placed ${count} order${count !== 1 ? 's' : ''} with us.`),
          );
          root.appendChild(stack);
        })
        .catch(console.error);
    },
  );
  ```

* ####

  ##### Description

  Fetch the customer's saved addresses and display each one. This example queries the \`addresses\` field from the Customer Account API and renders the city, zone code, and territory code for each address.

  ##### React

  ```tsx
  import React, {useEffect, useState} from 'react';
  import {reactExtension} from '@shopify/ui-extensions-react/customer-account';
  import {BlockStack, Text} from '@shopify/ui-extensions/customer-account';

  const API_VERSION = '2025-07';

  export default reactExtension(
    'customer-account.order-status.block.render',
    () => <Extension />,
  );

  function Extension() {
    const [addresses, setAddresses] = useState<{city?: string; zoneCode?: string; territoryCode?: string}[]>([]);

    useEffect(() => {
      fetch(`shopify://customer-account/api/${API_VERSION}/graphql.json`, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          query: `query {
            customer {
              addresses(first: 3) {
                nodes { city zoneCode territoryCode }
              }
            }
          }`,
        }),
      })
        .then((res) => res.json())
        .then(({data}) => {
          if (!data.customer) return;
          setAddresses(data.customer.addresses.nodes);
        })
        .catch(console.error);
    }, []);

    if (addresses.length === 0) return null;
    return (
      <BlockStack>
        <Text emphasis="bold">Saved addresses</Text>
        {addresses.map((addr, i) => (
          <Text key={i}>
            {[addr.city, addr.zoneCode, addr.territoryCode].filter(Boolean).join(', ')}
          </Text>
        ))}
      </BlockStack>
    );
  }
  ```

  ##### TS

  ```ts
  import {extension, BlockStack, Text} from '@shopify/ui-extensions/customer-account';

  const API_VERSION = '2025-07';

  export default extension(
    'customer-account.order-status.block.render',
    (root, api) => {
      fetch(`shopify://customer-account/api/${API_VERSION}/graphql.json`, {
        method: 'POST',
        headers: {'Content-Type': 'application/json'},
        body: JSON.stringify({
          query: `query {
            customer {
              addresses(first: 3) {
                nodes { city zoneCode territoryCode }
              }
            }
          }`,
        }),
      })
        .then((res) => res.json())
        .then(({data}) => {
          if (!data.customer) return;
          const addrs = data.customer.addresses.nodes;
          if (addrs.length === 0) return;
          const stack = root.createComponent(BlockStack, {});
          stack.appendChild(root.createComponent(Text, {emphasis: 'bold'}, 'Saved addresses'));
          for (const addr of addrs) {
            stack.appendChild(
              root.createComponent(Text, {}, [addr.city, addr.zoneCode, addr.territoryCode].filter(Boolean).join(', ')),
            );
          }
          root.appendChild(stack);
        })
        .catch(console.error);
    },
  );
  ```

***

## Best practices

* **Use the `shopify://` protocol**: Always use `shopify://customer-account/api/` as the base URL for Customer Account API requests. Don't use absolute URLs.
* **Handle GraphQL errors**: The API returns errors in the `errors` array of the response. Always check for errors before using the `data` field.

***

## Limitations

* The Customer Account API is a GraphQL API accessed using `fetch()`. It doesn't expose typed properties like other Account APIs.
* The data available depends on the buyer's authentication state and the app's access scopes.

***