Set up customer accounts

With customer accounts, customers can log in to your storefront, view their profile and order history, and check out as known customers. Hydrogen provides the Customer Account API client, OAuth route handlers, and session helpers. Your app owns the session storage and the account UI. This guide shows you how to wire customer accounts into your storefront and test them locally.

Anchor to How it worksHow it works

1. A customer selects a login link that points to /account/login.
2. Hydrogen's handler redirects the customer to Shopify's hosted login page.
3. After the customer logs in, Shopify redirects back to /account/authorize. The handler exchanges the authorization code for tokens and stores them in your session.
4. Your server reads the access token from the session and queries the Customer Account API.
5. When the access token expires, /account/refresh gets a new one. A POST request to /account/logout ends the session.

Hydrogen owns these four routes through handleShopifyRoutes(), so you don't need to write login, authorize, refresh, or logout logic.

Anchor to RequirementsRequirements

• Connect a real store. mock.shop doesn't support the Customer Account API.
• Wire request handlers and a Storefront API client.
• Serve your storefront over HTTPS, on a hostname other than localhost. For local development, refer to Step 6.

Anchor to Step 1: Configure the Customer Account APIStep 1: Configure the Customer Account API

In the Shopify admin, open the Headless or Hydrogen sales channel, select your storefront, and open the Customer Account API settings. Copy the client ID, then add the following values to your server environment:

NEXT_PUBLIC_SHOP_ID=<your numeric shop ID>
NEXT_PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID=<your Customer Account API client ID>
SESSION_SECRET=<a random string of 32 or more characters>
SITE_ORIGIN=https://local.tryhydrogen.dev:5173

SHOP_ID=<your numeric shop ID>
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID=<your Customer Account API client ID>
SESSION_SECRET=<a random string of 32 or more characters>

In Next.js, the shop ID and client ID use the NEXT_PUBLIC_ prefix, and you also set SITE_ORIGIN to the origin that customers visit. Server Components can't read the request URL, so they build the request that reads the session from SITE_ORIGIN.

In the same settings, register your storefront's callback URI, JavaScript origin, and logout URI. The callback URI is your storefront origin plus /account/authorize.

Anchor to Step 2: Create the customer sessionStep 2: Create the customer session

Create the customer session once, at module scope, with createCustomerSession(). When you reuse it across requests, concurrent token refreshes for the same customer share one request to Shopify.

The customer session reads and writes tokens through a session manager that you create for each request. A session manager is an object with getSessionOrigin(), getSessionItem(), setSessionItem(), removeSessionItem(), and an optional commit() that returns the Set-Cookie headers to add to the response. Back it with protected server storage or an HttpOnly cookie. Never store tokens in browser storage or send them to client components.

env stands for your server environment. Read the variables from Step 1 with your framework's environment API. The module also exports a helper that creates a Customer Account API client for each request, so the client shares the request context with your Storefront API client.

Anchor to Create a session managerCreate a session manager

The session manager is app code, so you choose where tokens live. The following session manager keeps them in a signed, HttpOnly cookie. It uses @remix-run/cookie and @remix-run/session, which work with any framework that uses standard Request objects:

A signed cookie is tamper-proof, but whoever holds it can read its contents. Vercel Shop, Vercel's Next.js template, uses an encrypted cookie instead. You can copy its session code from lib/auth/server.ts. For production, prefer opaque server-side session storage.

Anchor to Separate read-only and writable sessionsSeparate read-only and writable sessions

Hydrogen types session managers by what the caller can do:

• A ReadonlyCustomerSessionManager can read the session. Use it in render paths that can't set cookies, like Next.js Server Components, layouts, and header UI.
• A WritableCustomerSessionManager can also commit changes. Use it only where the response can carry a Set-Cookie header, like route handlers, Next.js proxy.ts, and React Router middleware.

Token refresh changes the session, so getOrRefreshAccessToken() requires a writable session manager. TypeScript rejects the call when you have only a read-only one.

Anchor to Step 3: Register the account handlersStep 3: Register the account handlers

Create the account handlers once with createCustomerAccountServerHandlers(), then pass them to handleShopifyRoutes() along with the request's session manager. This example shows only the customer account parts of your server request handler. For the full wiring, refer to Request handlers.

Call this from the request handler that runs before your router, and pass the request context and session manager to your page data through request-scoped context. For React Router and Next.js code, refer to Framework wiring.

Committing the session after your router runs saves any tokens that a page refreshed.

In Next.js, proxy.ts returns before the page renders, so it can't commit tokens that a page refreshes. Pass requestContext.getForwardedRequestHeaders() to the rendered request instead of calling next(). Pages can only read the session, as described in Step 5.

The handlers own GET /account/login, GET /account/authorize, GET /account/refresh, and POST /account/logout. They sanitize return_to parameters, check that logout requests are same-origin POST requests, set cache-control: no-store, and commit session cookies on their own responses. If you replace a handler with custom logic, then keep all of these safeguards.

Use the same request context for Storefront API and Customer Account API work in a request. Customer Account API reads mark the response as personalized, so apply the request context's response headers at your final response boundary.

Anchor to Step 4: Sync cart buyer identityStep 4: Sync cart buyer identity

By default, the cart and the customer session are independent. To attach the logged-in customer to their cart, create the cart handlers with the same customer session, then pass the cart handlers to the account handlers:

Register both handler groups with handleShopifyRoutes(), as in Step 3. Both groups must share one customer session. TypeScript rejects cart handlers that you created without customerSession.

With this wiring, Hydrogen keeps the cart in sync with the session:

• New carts include the logged-in customer's buyer identity, and checkout URLs for authenticated carts include logged_in=true.
• Login and token refresh attach the customer to the cart in the request's cart cookie.
• Logout, or a refresh that Shopify rejects, detaches the customer from the cart.

Sync never blocks a login or logout redirect. If detaching fails, the handler expires the cart cookie, so a shared device doesn't keep a cart that belongs to the previous customer.

Anchor to Step 5: Build the account pageStep 5: Build the account page

Hydrogen doesn't include account UI, so build at least a minimal /account page. Without one, customers can't reach the login flow.

Query the Customer Account API with gql() and createCustomerAccountClient() from @shopify/hydrogen/customer-account. Use them only in server code, and pass the access token with each query. The typed queries setup validates Customer Account API documents too.

Start with a data function that loads the account and returns a plain result that any UI can render. How it gets a usable access token depends on whether the page can set cookies:

Then render the result:

import type {Account} from './account';

export function renderAccount(root: HTMLElement, account: Account) {
  const main = document.createElement('main');

  if (account.status === 'signed-out') {
    main.innerHTML = `
      <h1>Account</h1>
      <a href="/account/login?return_to=/account">Log in</a>
    `;
  } else if (account.status === 'error') {
    main.innerHTML = `<p role="alert">We couldn't load your account.</p>`;
  } else {
    const {customer} = account;
    const heading = document.createElement('h1');
    heading.textContent = `${customer.firstName ?? ''} ${customer.lastName ?? ''}`;
    const email = document.createElement('p');
    email.textContent = customer.emailAddress?.emailAddress ?? '';
    const logout = document.createElement('form');
    logout.method = 'post';
    logout.action = '/account/logout';
    logout.innerHTML = '<button type="submit">Log out</button>';
    main.append(heading, email, logout);
  }

  root.replaceChildren(main);
}

import type {Account as AccountData} from '~/lib/account';

export function Account({account}: {account: AccountData}) {
  if (account.status === 'signed-out') {
    return (
      <main>
        <h1>Account</h1>
        <a href="/account/login?return_to=/account">Log in</a>
      </main>
    );
  }

  if (account.status === 'error') {
    return <p role="alert">We couldn't load your account.</p>;
  }

  const {customer} = account;
  return (
    <main>
      <h1>
        {customer.firstName} {customer.lastName}
      </h1>
      <p>{customer.emailAddress?.emailAddress}</p>
      <form method="post" action="/account/logout">
        <button type="submit">Log out</button>
      </form>
    </main>
  );
}

<script setup lang="ts">
import type {Account} from '~/lib/account';

defineProps<{account: Account}>();
</script>

<template>
  <main v-if="account.status === 'signed-out'">
    <h1>Account</h1>
    <a href="/account/login?return_to=/account">Log in</a>
  </main>
  <p v-else-if="account.status === 'error'" role="alert">
    We couldn't load your account.
  </p>
  <main v-else>
    <h1>{{ account.customer.firstName }} {{ account.customer.lastName }}</h1>
    <p>{{ account.customer.emailAddress?.emailAddress }}</p>
    <form method="post" action="/account/logout">
      <button type="submit">Log out</button>
    </form>
  </main>
</template>

Follow these rules for account UI:

• Use a plain <a> element for login links and a plain <form method="post"> for logout. The handlers return redirects to Shopify's hosted pages, which client-side navigation, like next/link or a React Router <Form>, can't follow.
• For signed-in state in shared UI, like a header account link, call isLoggedIn(). It treats a refreshable session as logged in without refreshing tokens. Wrap the UI in <Suspense> so the page shell renders first.
• Gate Customer Account API calls on an access token, as loadAccount() does, not on isLoggedIn(). getAccessToken() returns a token only when the token is usable right now.
• If isLoggedIn() returns false, then show a login link instead of redirecting to /account/refresh.
• Render only the profile fields you need. Never serialize tokens or session objects into loader data or HTML.

To add order history and other account data, refer to the Customer Account API reference.

Anchor to Step 6: Test sign-in locally with HTTPSStep 6: Test sign-in locally with HTTPS

Customer Account API login, logout, and callbacks require an HTTPS origin that isn't localhost, and that exactly matches the URLs registered in the Shopify admin. local.tryhydrogen.dev is a Shopify-owned domain that resolves to 127.0.0.1, so you can use it as a stable local hostname.

Anchor to Register local URLsRegister local URLs

To register your local URLs by hand, open your storefront's Customer Account API settings in the Headless or Hydrogen sales channel and enter the following values:

The JavaScript origin has no port, because Shopify rejects JavaScript origins that include one.

Anchor to Next stepsNext steps

Customer Account API

Explore the queries and mutations for customer data, orders, and addresses.

Customer accounts reference

Review the customer session, account client, and account route handlers.

Build cart UI

Build a cart that carries the logged-in customer to checkout.