The Shopify Customer Account API: accounts in headless builds

The Customer Account API exists for one reason: to let a customer read and change their own data, authenticated as themselves. That sounds like a small distinction. It's the entire security model.

The problem it solves

In a Liquid theme, customer accounts are handled by Shopify. The customer logs in, and {{ customer }} is populated with their data. Nothing to build.

In a headless storefront there's no such object. So you need order history, addresses and profile — and the obvious wrong answer is to use the Admin API from your server, authenticating as the merchant, and decide which customer is asking.

That works, and it means your server holds a token that can read every customer's data, with your own code as the only thing preventing one customer seeing another's orders. One bug in that check and you have a data breach.

The Customer Account API removes the problem: the customer authenticates, you get a token scoped to that customer, and the API physically cannot return anyone else's data.

What it gives you

• Authentication — login, logout, session, with Shopify handling passwords, one-time codes and recovery.
• Profile — name, email, phone.
• Addresses — read, create, update, delete, set default.
• Order history and order detail, for that customer only.
• Subscription contracts, where subscriptions are in use — subscriptions.
• A customer access token you attach to a cart's buyer identity so checkout is pre-filled and the order is attributed — the Cart API.

How the authentication works

It's OAuth, with the customer as the authenticated party rather than the merchant. The flow:

1. Redirect the customer to Shopify's login.
2. They authenticate — Shopify handles the credentials, which means you never touch a customer password.
3. You receive a code and exchange it for a customer access token.
4. You call the API with that token, on their behalf.
5. Refresh it as needed; it's short-lived by design.

That Shopify handles credentials is worth valuing. Password storage, reset flows, rate limiting and account-takeover protection are all problems you don't want.

How it differs from the other APIs

The full map is in Shopify APIs explained.

When you need it

• A headless storefront with customer accounts. Effectively mandatory.
• A mobile app where customers log in.
• A separate customer portal — a returns portal, a subscription management page, a trade account area — living outside the theme.
• Anywhere a customer needs to see their own orders outside a Liquid theme.

When you don't

If you're building a conventional Liquid theme, Shopify's own customer accounts already work. There's nothing to build and no reason to reach for this.

The middle case: a theme that needs one richer account feature. Sometimes that's a small custom app with an admin-side check rather than a headless account layer — simpler, if the feature is narrow.

Practical notes

• Tokens are short-lived. Implement refresh from the start, or customers get logged out mid-session and nobody can reproduce it.
• Handle the not-logged-in state properly. Every account page needs a sensible unauthenticated view.
• Don't cache customer data in any shared cache. Obvious, and it still happens.
• Order history can be long. Paginate it.
• Test the recovery flows — password reset, email change, first login after checkout as a guest.

The mistake worth avoiding

Building customer accounts on the Admin API because it was quicker. It works in development, passes review because the check is there, and is one refactor away from returning the wrong customer's orders.

If a customer is asking for their own data, they should be the one authenticated.

The Customer Account API isn't a convenience layer. It's the difference between an access-control bug being impossible and being one line of code away.