---
title: Customer Account API
description: >-
  The Customer Account API lets your extension query the Customer Account
  GraphQL API using the global `fetch()`. Use this API to fetch customer data
  like order history, addresses, and profile information.
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/api/customer-account-ui-extensions/2025-10/upgrading-to-2025-10) 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 this API to fetch customer data like order history, addresses, and profile information.

Examples

### Examples

* #### Fetch customer name

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

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

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

* #### Fetch order history

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

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

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

* #### Fetch customer addresses

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

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

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