Choose a version:

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

Anchor to Use casesUse 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, or modify order information directly through GraphQL mutations.

Support

Targets (25)

Supported targets

Examples

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>

);

}

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

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

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

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

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

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

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

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

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.

Was this page helpful?