Customer Account API Local Development

This guide is for Shopify Hydrogen storefronts. Building on Next.js? See the Next.js overview.

The Customer Account API requires OAuth 2.0 flows with HTTPS callback URLs — which means http://localhost won’t work. Hydrogen 2026.10 refuses to build a login URL over plain HTTP, so /account/login fails under npm run dev by design. This guide walks you through running the Pilot theme locally with full Customer Account API support.

The setup differs depending on your store type:

Paid stores (Basic, Shopify, Advanced, Plus) → use the built-in dev:https command, which serves the dev server over HTTPS and registers its URLs for you
Development stores (Partner/Staff) → use ngrok or Cloudflare Tunnel with manual OAuth configuration in the Headless sales channel app

Hydrogen 2026.10 owns the fixed, unprefixed routes /account/login, /account/authorize, /account/refresh and /account/logout, registered in server.ts with createCustomerAccountServerHandlers(). Link to them with a plain <a> or <form>, never React Router’s <Link> or <Form>: they answer with a redirect that client-side routing cannot follow.
The market travels in the query string. An account page visited without a session redirects to /account/login?return_to=/de-de/account&locale=de, so the shopper signs in on Shopify’s German login page and comes back to the German market.
The customer’s tokens live in the signed session cookie (SESSION_SECRET).

See Step 11 of the v6 migration guide for the server code.

Prerequisites

A Shopify store with the Hydrogen or Headless sales channel installed
Customer accounts enabled in your Shopify admin
Shopify CLI installed (@shopify/cli 4.4.0 or later, with @shopify/cli-hydrogen 13.0.4 or later so the dev server can register its URLs for you)
Your Hydrogen project linked to your store (shopify hydrogen link)

Step 1: Enable Customer Accounts

From your Shopify admin, go to Settings > Customer accounts
Under Accounts in online store and checkout, click Edit
Select Customer accounts
Click Save

Step 2: Link Your Project

If you have an existing .shopify/project.json pointing to a different store, delete it first:

rm .shopify/project.json

Then link to the correct store:

shopify hydrogen link

If .shopify/project.json points to a store where your account lacks Hydrogen/Headless channel access, all shopify hydrogen commands will fail with ACCESS_DENIED — including shopify hydrogen link itself.

Step 3: Pull Environment Variables

shopify hydrogen env pull

Verify your .env has these variables:

SESSION_SECRET="any-long-random-string"
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID=shp_xxxxx
PUBLIC_STOREFRONT_API_TOKEN="your-storefront-api-token"
PUBLIC_STORE_DOMAIN="your-store.myshopify.com"
SHOP_ID=your-numeric-shop-id

SHOP_ID is the numeric shop ID, not a GID or domain. Leave SHOP_ID and PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID empty to run the storefront without customer accounts.

When deploying to Shopify Oxygen, these variables are injected automatically — no manual setup needed for production.

Option A: Paid Stores (Basic to Plus)

For stores on a paid Shopify plan, use the built-in dev:https command. This is the easiest approach — it serves the dev server over HTTPS and configures OAuth automatically.

The dev:https script is already configured in the Pilot theme’s package.json — no additional setup needed.

Start the HTTPS dev server

npm run dev:https

This runs the same vite dev --port 3456 as npm run dev, with Hydrogen’s localHttps Vite plugin turned on in vite.config.ts:

import { localHttps } from "@shopify/hydrogen/vite";

plugins: [
  localHttps({ enabled: process.env.npm_lifecycle_event === "dev:https" }),
  // ...
],

The plugin does two things:

Serves HTTPS locally — at https://local.tryhydrogen.dev:3456, a Shopify-owned name that resolves to 127.0.0.1, with a locally trusted certificate. On the first run it installs a local certificate authority, which may prompt for your password. To do that ahead of time, run npx hydrogen certs install.
Syncs OAuth credentials — uses Shopify CLI to add the Callback URI, JavaScript Origin, and Logout URI to your storefront’s Customer Account API settings

Open the HTTPS URL

Open the HTTPS URL the dev server prints, for example https://local.tryhydrogen.dev:3456, and navigate to /account to test login. If Shopify CLI is missing, outdated or the push fails, the dev server keeps running and prints the values. Set them manually in Hydrogen > Storefront > Customer Account API settings:

Field	Value
Callback URI(s)	`https://local.tryhydrogen.dev:3456/account/authorize`
JavaScript origin(s)	`https://local.tryhydrogen.dev` (no port: Shopify rejects origins with a port)
Logout URI(s)	`https://local.tryhydrogen.dev:3456`, plus every market’s home page you sign out from (`https://local.tryhydrogen.dev:3456/de-de`, …)

Do not use http://localhost:3456 for customer account testing — OAuth redirects will fail on non-HTTPS origins.

Option B: Development Stores — Manual Tunnel Setup

For Shopify development stores (Partner/Staff), the automatic Customer Account API setup is not available. You must use a third-party tunneling service and manually configure the Customer Account API in the Headless sales channel app.

Set up a tunnel

Choose either ngrok or Cloudflare Tunnel:

ngrok
Cloudflare Tunnel

# Install ngrok
brew install ngrok

# Start a tunnel to your dev server
ngrok http 3456

Use a static ngrok domain so you don’t have to reconfigure OAuth settings every time you restart.

# Install cloudflared
brew install cloudflare/cloudflare/cloudflared

# Start a quick tunnel
cloudflared tunnel --url http://localhost:3456

Note: Quick tunnels generate a random URL each time. Use a named tunnel for a stable URL.

Configure Customer Account API

For development stores, configure this in the Headless sales channel app:

Open your Shopify admin → Settings > Customer accounts
Find Customer Account API and open Application setup
Ensure the client type is set to Public
Update the following fields with your tunnel URL:

Field	Value
Callback URI(s)	`https://your-tunnel-domain/account/authorize`
JavaScript origin(s)	`https://your-tunnel-domain`
Logout URI	`https://your-tunnel-domain`, plus each market’s home page (`https://your-tunnel-domain/de-de`, …)

Update Content Security Policy

In app/weaverse/csp.ts, add the tunnel domain to connectSrc:

connectSrc: [
  "https://your-tunnel-domain",
  "vimeo.com",
  // ... other sources
],

See Content Security Policy for how these directives become the header.

Start the dev server

npm run dev

Then access your storefront via the tunnel URL (not localhost). Pilot honors the tunnel’s x-forwarded-proto: https header, so the login URL uses HTTPS.

Account Routes in Pilot Theme

Login, OAuth callback, token refresh and logout are handled by Hydrogen’s Customer Account handlers at /account/login, /account/authorize, /account/refresh and /account/logout, not by route files. The Pilot theme includes the account pages at app/routes/account/:

Route	Purpose
`dashboard/index.tsx`	Account dashboard
`dashboard/account-details.tsx`	Customer profile details
`dashboard/address-book.tsx`	Saved addresses
`dashboard/orders-history.tsx`	Order history
`profile.tsx`	Edit profile
`edit.tsx`	Edit account settings
`orders/list.tsx`	Orders list
`orders/order.tsx`	Single order view
`address/index.tsx`	Address management
`address/list.tsx`	Address list

Source: Pilot theme routes

Customer account pages are code-based routes — they are not editable through Weaverse Studio’s visual editor. Any layout or design changes need to be done directly in the route files.

Troubleshooting

ACCESS_DENIED error on shopify hydrogen commands

Your .shopify/project.json is pointing to a store where you don’t have channel access. Delete it and re-link:

rm .shopify/project.json
shopify hydrogen link

OAuth redirect mismatch error

The Callback URI, JavaScript origin and Logout URI in your Shopify admin must exactly match the URL you are browsing, including the port (except the JavaScript origin, which has none). For paid stores using dev:https, this is synced automatically. For dev stores, update it manually. A sign-in that lands on /account?login=failed or loops back to Shopify usually has a mismatch here.

Port already in use

The dev server uses port 3456 and exits when the port is taken. To free it:

lsof -ti:3456 | xargs kill

Next Steps

Read the Customer Account API reference for available queries and mutations
Follow Shopify’s Using Customer Account API with Hydrogen tutorial
Learn about Weaverse environment variables

Environment

Building Components

Content Management

Internationalization

Security & Privacy

Pages & Routing

Advanced

Customer Account API Local Development

Customer Account API Local Development

Prerequisites

Step 1: Enable Customer Accounts

Step 2: Link Your Project

Step 3: Pull Environment Variables

Option A: Paid Stores (Basic to Plus)

Start the HTTPS dev server

Open the HTTPS URL

Option B: Development Stores — Manual Tunnel Setup

Set up a tunnel

Configure Customer Account API

Update Content Security Policy

Start the dev server

Account Routes in Pilot Theme

Troubleshooting

Next Steps

​Customer Account API Local Development

​How Sign-In Works

​Prerequisites

​Step 1: Enable Customer Accounts

​Step 2: Link Your Project

​Step 3: Pull Environment Variables

​Option A: Paid Stores (Basic to Plus)

​Start the HTTPS dev server

​Open the HTTPS URL

​Option B: Development Stores — Manual Tunnel Setup

​Set up a tunnel

​Configure Customer Account API

​Update Content Security Policy

​Start the dev server

​Account Routes in Pilot Theme

​Troubleshooting

​Next Steps

Customer Account API Local Development

How Sign-In Works

Prerequisites

Step 1: Enable Customer Accounts

Step 2: Link Your Project

Step 3: Pull Environment Variables

Option A: Paid Stores (Basic to Plus)

Start the HTTPS dev server

Open the HTTPS URL

Option B: Development Stores — Manual Tunnel Setup

Set up a tunnel

Configure Customer Account API

Update Content Security Policy

Start the dev server

Account Routes in Pilot Theme

Troubleshooting

Next Steps