Choose a version:

Customer Account API

The Customer Account API lets you query the GraphQL Customer Account API directly from your extension using the global fetch() function. Use this API to access detailed customer data, including profile information, order history, and saved addresses.

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/2026-04/graphql.json'). Authentication is handled automatically, so you don't need a session token.

The data available depends on the buyer's authentication state and your app's access scopes.

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 (24)

Supported targets

Examples

jsx

import '@shopify/ui-extensions/preact';

import {render} from 'preact';

import {useState, useEffect} from 'preact/hooks';

export default async () => {

render(<Extension />, document.body);

};

const API_VERSION = '2025-10';

function Extension() {

const [name, setName] = useState(null);

useEffect(() => {

fetch(

`shopify://customer-account/api/${API_VERSION}/graphql.json`,

{

method: 'POST',

headers: {

'Content-Type': 'application/json',

body: JSON.stringify({

query: `query {

customer {

firstName

lastName

}

}`,

}),

)

.then((response) => response.json())

.then(({data: {customer}}) => {

setName(customer);

})

.catch(console.error);

}, []);

if (!name) {

return <s-text>Loading…</s-text>;

}

return (

<s-box padding="base">

<s-text type="strong">

Hello, {name.firstName} {name.lastName}!

</s-text>

</s-box>

);

}

Examples

Description

Query the buyer's name from the GraphQL Customer Account API. This example uses `fetch()` with a GraphQL query for `customer { firstName lastName }` and displays the result with `useState` and `useEffect`.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const API_VERSION = '2025-10';

function Extension() {
  const [name, setName] = useState(null);

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

  if (!name) {
    return <s-text>Loading…</s-text>;
  }

  return (
    <s-box padding="base">
      <s-text type="strong">
        Hello, {name.firstName} {name.lastName}!
      </s-text>
    </s-box>
  );
}

Description

Fetch the buyer's past orders to display a purchase history. This example sends a GraphQL query for the last five orders and renders each order's name and total price.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const API_VERSION = '2025-10';

function Extension() {
  const [orders, setOrders] = useState(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: 5) {
                edges {
                  node {
                    name
                    totalPrice {
                      amount
                    }
                  }
                }
              }
            }
          }`,
        }),
      },
    )
      .then((response) => response.json())
      .then(({data: {customer}}) => {
        if (!customer) return;
        setOrders(
          customer.orders.edges.map(
            (edge) => edge.node,
          ),
        );
      })
      .catch(console.error);
  }, []);

  if (!orders) {
    return <s-text>Loading orders…</s-text>;
  }

  return (
    <s-box padding="base">
      <s-stack direction="block" gap="small-200">
        <s-text type="strong">
          Recent Orders
        </s-text>
        {orders.map((order) => (
          <s-stack
            key={order.name}
            direction="inline"
            gap="base"
          >
            <s-text type="strong">
              {order.name}
            </s-text>
            <s-text>
              ${order.totalPrice.amount}
            </s-text>
          </s-stack>
        ))}
      </s-stack>
    </s-box>
  );
}

Description

Retrieve the buyer's saved addresses from their customer account. This example queries `customer { addresses }` via the GraphQL API and displays each address.

jsx

import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState, useEffect} from 'preact/hooks';

export default async () => {
  render(<Extension />, document.body);
};

const API_VERSION = '2025-10';

function Extension() {
  const [addresses, setAddresses] =
    useState(null);

  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: 5) {
                edges {
                  node {
                    address1
                    city
                    zoneCode
                  }
                }
              }
            }
          }`,
        }),
      },
    )
      .then((response) => response.json())
      .then(({data: {customer}}) => {
        if (!customer) return;
        setAddresses(
          customer.addresses.edges.map(
            (edge) => edge.node,
          ),
        );
      })
      .catch(console.error);
  }, []);

  if (!addresses) {
    return <s-text>Loading addresses…</s-text>;
  }

  if (addresses.length === 0) {
    return (
      <s-text color="subdued">
        No saved addresses found.
      </s-text>
    );
  }

  return (
    <s-box padding="base">
      <s-stack direction="block" gap="base">
        <s-text type="strong">
          Saved Addresses
        </s-text>
        {addresses.map((address, index) => (
          <s-box key={index} padding="small-200">
            <s-stack
              direction="block"
              gap="small-200"
            >
              <s-text>{address.address1}</s-text>
              <s-text>
                {address.city},{' '}
                {address.zoneCode}
              </s-text>
            </s-stack>
          </s-box>
        ))}
      </s-stack>
    </s-box>
  );
}

Anchor to Best practicesBest practices

Specify an API version: Always include a specific API version in the request URL rather than using unstable, to ensure consistent behavior across deployments.
Handle errors gracefully: The fetch() call can fail due to network issues or authentication problems. Always check the response status and handle errors appropriately.

Was this page helpful?