Storefront API and Headless with Hydrogen

Three parties are involved in every headless request. Your storefront (browser, mobile app or server) renders the user interface. Shopify’s two headless APIs supply data and customer sessions. Checkout stays on Shopify: the cart returns a checkoutUrl and the buyer is redirected to it, which means checkout customization (checkout UI extensions, Shopify Functions, branding) applies to a headless storefront exactly as it does to a theme.

The Storefront API is GraphQL only: there is no REST Storefront API. The Customer Account API is also GraphQL only. Both can be called from any HTTP client. For development before a store exists, mock.shop is a public Storefront API with demo data that needs no store and no token (carts work and checkout is mocked, the Customer Account API is not available, and private tokens are rejected).

All queries go to one endpoint, which only accepts POST:

Source: Shopify: Storefront API endpoints and queries

The version is part of the path and follows the same quarterly calendar as the Admin API: a stable version is released at 17:00 UTC on the first day of January, April, July and October, is supported for at least 12 months, and overlaps the next version by at least 9 months. At the check date the supported versions are 2026-01, 2026-04, 2026-07 and 2026-10, with 2027-01 as the release candidate. A request to a retired version is served by the oldest supported one, so always pin the version in the URL. The Storefront API and the Customer Account API are versioned APIs; Hydrogen and Hydrogen React are libraries versioned by their own releases (Hydrogen 2026-10 uses Storefront API 2026-10).

The Storefront API has no maintenance-mode status in Shopify’s documentation or changelog. It is actively extended in 2026: the channelId argument on @inContext arrived in 2026-10, cart discount fields in 2026-04 and error codes in 2026-01. What Shopify has deprecated is the customer-scoped part of the API, covered in Legacy customer accounts.

The Storefront API supports three access modes. They differ in where the credential may live and in which features they unlock.

Source: Shopify: Storefront API authentication

A public token is created by the Admin API storefrontAccessTokenCreate mutation or by the Headless channel. A private token comes from the Headless channel (which provides both kinds automatically), from a delegate access token of a custom app, or from requesting unauthenticated access scopes on an existing access token. An app can have at most 100 active storefront access tokens per shop. Public access capacity scales with the number of buyers, measured by their IP address.

The Admin API call that creates a public token (an app with the right scope, not run against a store) is validated against the Admin 2026-10 schema:

Source: Shopify: storefrontAccessTokenCreate

The three request shapes, as curl commands with placeholders (documented from Shopify’s reference, not executed against a store):

Source: Shopify: Storefront API authentication

Rules that prevent the usual incidents:

A token created through the Headless channel carries the permissions chosen in the channel. For an app, the same permissions are the unauthenticated_* access scopes:

Source: Shopify: Unauthenticated access scopes

A missing scope does not fail the request: the field is simply not returned or the object is empty. When a Pocket Coffee product page shows no roast date, check that the metafield is exposed to the Storefront API and that the token can read metafields before debugging the query.

The Storefront API does not rate limit buyer traffic with a fixed requests-per-minute number: capacity scales with buyers. What is limited:

Shopify Plus bot protection applies to the Cart object, not to the Checkout object, and the Storefront API must not be used to duplicate functionality Shopify already provides (the API terms apply).

Errors follow GraphQL conventions, with one trap: most failures arrive as HTTP 200 with an errors array, because partial success is valid in GraphQL. Mutations report validation problems in userErrors, which must be requested.

Source: Shopify: Storefront API status and error codes

The Pocket Coffee product page needs the product, its options, the 18 variants with their SKUs and prices, and the roast date metafield. The query takes the market as variables so that prices and translations come from Shopify:

Source: Shopify: product query

This document validates against the Storefront API 2026-10 schema (and against the schema shipped with Hydrogen). A document with two mistakes is rejected:

The validator (the graphql package’s validate() against the introspection result) reports both:

The @inContext directive of the 2026-10 schema accepts these arguments, read from the introspection result:

Source: Shopify: Storefront API directives

The schema also declares the directives @defer (streamed responses; documented as available only in the unstable version), @include, @skip, @oneOf, @specifiedBy, @deprecated and @accessRestricted.

The rule from the Markets page applies without change: load each market’s prices explicitly through @inContext and treat Shopify as the source of truth, never compute a local price from the base price. The market is also what makes the Spanish and English storefronts of Pocket Coffee possible, so a storefront must send country and language on every query that returns prices or translated content. Hydrogen can supply the two variables for you, as shown below.

Other queries a storefront typically needs, all validated against the 2026-10 schema:

Source: Shopify: localization query

The localization query feeds a country and language selector, sitemap and urlRedirects replace what a theme gets for free (a headless storefront must serve its own /sitemap.xml and honour the merchant’s redirects), and predictiveSearch powers search-as-you-type. The productByHandle, collectionByHandle, pageByHandle and blogByHandle fields are deprecated in the schema: use product(handle:), collection(handle:), page(handle:) and blog(handle:).

A common mistake is sending Admin API traffic to the Storefront path: the bulk operation guides print their Admin examples with /api/<version>/graphql.json, which is the Storefront endpoint, while the Admin endpoint has the /admin/ segment. The two APIs also have different tokens, headers and schemas.

The tasks, in the order a project meets them:

Orders created by a Headless storefront are attributed to the channel, which gives sales reports and analytics by channel. If the storefront’s product URLs are not /products/<handle>, the storefront must redirect (with a 3XX) from the expected /products/<handle> path, and it should support cart permalinks; Hydrogen’s request handlers already answer cart permalinks.

Shopify’s plan comparison lists the number of headless storefronts: 1 on Basic, 1 on Grow, 1 on Advanced and 25 on Shopify Plus. The Oxygen limits in the next sections follow a similar pattern. Plans, prices and the full feature table are on the plans and Shopify Plus page.

Source: Shopify: Create and update a cart with the Storefront API

The cart ID has the form gid://shopify/Cart/<token>?key=<secret>, and every cart API needs the full ID. The key is a verification secret: without it, queries return the cart with the buyer’s private details (email, address) removed, and mutations fail with an error saying the cart does not exist. Treat the secret like a password: never put it in shareable links, public pages or client code, and write code that accepts a cart token of any format and length, because Shopify may change them. Hydrogen stores the ID in a cart cookie for you.

Pocket Coffee’s 250 g whole-bean Ethiopia variant (PC-ETH-WHL-250, 9.90 EUR: 8.90 plus 1.00 for Ethiopia) goes into a new cart with the Coffee Club code, the Spanish market and the visitor’s consent decision. The consent is passed to @inContext so it is encoded in the checkout URL:

with the variables:

Source: Shopify: cartCreate

Both the document and the variables were validated against the 2026-10 schema (the variables with GraphQL’s variable coercion: a string given for quantity is rejected with Int cannot represent non-integer value: "two"). The numeric IDs are placeholders; a real storefront reads ProductVariant IDs from a product query. The CartInput fields in the 2026-10 schema are attributes, lines, discountCodes, giftCardCodes, note, buyerIdentity, delivery, metafields and sourceName.

Coffee Club members get 10% off beans and free shipping above 40 EUR from a discount and a delivery customization that live on the Shopify side (Shopify Functions or the discounts the merchant configures): the storefront only has to send the cart to Shopify and show what comes back. This is why a headless cart must never compute totals itself.

Reading uses the cart query. The document below asks for the totals, the delivery options (delivery groups are based on the buyer identity’s default delivery address preference, or on the default address of the logged-in customer), and the lines with their SKUs:

Source: Shopify: cart query

The cart mutations that Pocket Coffee needs, also validated:

Source: Shopify: Create and update a cart with the Storefront API

Two details were caught by validation while writing these. cartDiscountCodesUpdate takes [String!]!, not [String!]: passing a nullable variable is a type error, and the mutation replaces all existing codes (an empty array removes them, and codes are case-insensitive), so the code the buyer already applied must be sent again with the new one. cartNoteUpdate takes String!. And cartMetafieldsSet takes CartMetafieldsSetInput with ownerId, key, type and value and no namespace field: the namespace is part of the key, as in custom.roast_date. A variables object that sets namespace is rejected with Field "namespace" is not defined by type "CartMetafieldsSetInput", whereas {"ownerId": "gid://shopify/Cart/<token>?key=<secret>", "key": "custom.roast_date", "type": "date", "value": "2026-10-20"} is accepted. Cart metafields can be copied to order metafields when a matching order metafield definition has the cart-to-order copyable capability enabled. Neither cartMetafieldsSet nor cartMetafieldDelete triggers Shopify Functions, so a change is not visible to Functions until the buyer goes to checkout or makes another cart interaction that triggers them.

The 2026-10 Storefront API schema has 26 cart mutations. Every one returns the cart (or the affected object) with userErrors and, for most, warnings.

Source: Shopify: Cart object

The completion mutations (cartPrepareForCompletion, cartSubmitForCompletion, cartPaymentUpdate and the cartCompletionAttempt poll) exist in the schema with one-line descriptions only; the standard path for a storefront is the redirect to checkoutUrl, and this page does not describe a custom completion flow.

Every cart mutation returns two lists with different meanings. userErrors mean the operation was not applied (code is a CartErrorCode such as INVALID, MINIMUM_NOT_MET, MAXIMUM_EXCEEDED, INVALID_INCREMENT, INVALID_MERCHANDISE_LINE, NOTE_TOO_LONG, MISSING_DISCOUNT_CODE, VARIANT_REQUIRES_SELLING_PLAN or CART_TOO_LARGE; the 2026-10 enum has more than sixty values, including address-validation and payment codes). warnings confirm that the mutation succeeded and describe automatic changes Shopify made to the cart; the client may address them but is not required to (code is a CartWarningCode, target is the ID of the object concerned):

Source: Shopify: Cart warnings

A storefront that ignores warnings shows a quantity of 2 when only 1 is in stock, which is the classic headless overselling bug. Hydrogen’s cart store keeps both lists per entity, as described below.

The buyer reaches checkout by following cart.checkoutUrl, which should be requested when the buyer is ready to check out (it can be re-requested when stale). Shopify then runs checkout with everything the cart carried: the market, the discounts, the attributes and metafields that checkout UI extensions and Functions read, and the visitor consent.

For a signed-in buyer there are two ways to carry the identity into checkout, and they are independent:

Source: Shopify: Authenticate buyers in checkout

When the cart carries a customer token, server-side requests that fetch checkoutUrl must send the Shopify-Storefront-Buyer-IP header, or the logged-in experience is lost.

Source: Shopify: About the Cart API

Links of the form /cart/<variantId>:<quantity> (cart permalinks) are how apps, emails and QR codes put goods in a cart, and /checkout takes a buyer to checkout for the current cart. Liquid themes answer them natively. A headless storefront must answer them itself, which Hydrogen’s request handlers do (below). The same handlers answer the Ajax cart URLs /cart.js, /cart/add.js, /cart/update.js, /cart/change.js and /cart/clear.js that theme apps call, so apps written for themes keep working.

A Hydrogen storefront has three layers. Your framework owns routing, rendering, data loading and the interface. Hydrogen owns the Shopify-specific logic: the Storefront API client, the cart, and the handful of routes a Shopify storefront needs. Shopify owns the Storefront API, the Customer Account API and checkout. On the server, Hydrogen’s request handlers run around your framework’s router; in the browser, Hydrogen keeps the cart, product form, collection and search state in stores that your interface reads, and changes go back to Hydrogen through native HTML forms, so customers can still shop before JavaScript loads or if it fails.

Hydrogen’s logic lives in a framework-agnostic core that depends only on fetch and other web platform APIs.

Source: Shopify: Hydrogen

Frameworks without a packaged binding (Astro, SvelteKit, SolidStart) use the core directly. The package also exports the Storefront and Customer Account schemas (@shopify/hydrogen/storefront.schema.json and @shopify/hydrogen/customer-account.schema.json), the generated types, a hydrogen binary with the commands setup, skills sync, skills check, gql check, certs install and certs uninstall, and 20 agent skills (for example hydrogen-request-handlers, hydrogen-customer-account, hydrogen-oxygen and migrate-to-hydrogen-2026-10) that describe the API of the installed version for coding agents.

Source: Shopify: Hydrogen releases

There are two ways to start, and they use the same package.

Source: Shopify: Get started with Hydrogen

Deploying the React Router template creates the storefront in the Hydrogen channel, creates a GitHub repository from the template with an Oxygen workflow, generates the store’s tokens and deploys on every push. Deploying Vercel Shop starts from a Headless channel storefront (public token, Storefront API permissions, products published to the Headless channel, the myshopify.com domain and the numeric shop ID) and asks Vercel for NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN, NEXT_PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN and NEXT_PUBLIC_SHOPIFY_SHOP_ID. The Node.js version required is 22 or 24 for the React Router template and 24 for Vercel Shop (which also needs pnpm 12).

To add Hydrogen to a project, run the setup command in it (shown here as documented; it was not run, because setup installs the package into a project and writes agent skills into .claude/skills and .agents/skills):

Source: Shopify: Add Hydrogen to an existing project

Then link the local project to the storefront of the Hydrogen channel and pull its variables (commands from the CLI help of version 5.0.0; they need a store login and were not run):

Source: Shopify CLI: hydrogen link

createShopifyRequestContext() creates one object per incoming request that every Hydrogen server API shares. It carries request-derived data, the i18n (country and language) and the optional buyerIp you supply, captured Shopify cookies and privacy markers for the response. Three rules:

createStorefrontClient() takes a type, a requestContext and a config. Queries are written with gql() and run with client.graphql(query, {variables}); there are no helper methods such as client.product().

Source: Shopify: Query the Storefront API

Private tokens are server-only: creating a private client in the browser throws, and creating one without a buyer IP in the request context throws too. The buyer IP is read from a header that the host sets and buyers cannot spoof; Hydrogen does not guess it.

Source: Shopify: About deploying Hydrogen storefronts

The Pocket Coffee client factory, request scoped, with the market resolved from the URL (/en for English in Spain, /us for the USD market, Spanish in Spain as the default):

Source: Shopify: Query the Storefront API

The client reads PUBLIC_STORE_DOMAIN, PRIVATE_STOREFRONT_API_TOKEN and PUBLIC_STOREFRONT_ID from the server environment (env above stands for the framework’s environment API: process.env on Node, the Worker’s env argument on Oxygen). The market resolver was run and returns {"country":"ES","language":"ES","pathPrefix":""} for /products/single-origin-beans, {"country":"ES","language":"EN","pathPrefix":"/en"} for /en/products/..., {"country":"US","language":"EN","pathPrefix":"/us"} for /us/cart and the default market for an unknown prefix such as /fr/products/x.

Hydrogen fills the $country and $language variables from the request context whenever the query declares them, and the request context’s values override variables. It does not add @inContext for you: a query that does not declare the variables and use them in @inContext returns the store’s default market.

A runnable check of the client (the package installed from npm, fetch replaced by a stand-in that records the request; placeholders instead of tokens):

Source: Shopify: Query the Storefront API

Output of the run with @shopify/hydrogen 2026.10.2 on Node.js 24:

The run shows the rules in practice: the version in the URL is 2026-10, country and language were injected from the request context, the public client sends X-Shopify-Storefront-Access-Token, and only the private client sends the buyer IP header. Creating a private client from a request context without buyerIp throws TypeError: requestContext.buyerIp is required for private Storefront API clients.

Errors: transport failures throw and GraphQL errors are returned. A non-2xx answer throws StorefrontApiError (a timeout throws StorefrontTimeoutError, which extends it), while an HTTP 200 that carries an errors array does not throw, because partial success is valid in GraphQL. In the run, a stand-in answering 500 raised StorefrontApiError, and one answering 200 with {"errors":[{"message":"Throttled","extensions":{"code":"THROTTLED"}}]} returned the errors array next to data. Code that checks only try/catch therefore misses most Storefront API failures:

Source: Shopify: Handle errors

A query with a missing or renamed field can pass tsc and fail at runtime as an empty result, which on a product page looks like a missing product and turns into a misleading 404. Validate queries in CI, as described next.

@shopify/hydrogen/ts-plugin gives the editor diagnostics and types for gql() documents, and hydrogen gql check runs the same validation headlessly against the schemas packaged with Hydrogen. Configure the plugin in tsconfig.json:

Source: Shopify: Typed queries and validation

The plugin generates storefront-graphql-env.d.ts and customer-account-graphql-env.d.ts at the project root; add both to .gitignore. In a scratch project with @shopify/hydrogen 2026.10.2 and that tsconfig.json, a correct document and a document with a typo were checked with the commands below:

For the correct document the command printed No problems found and exited 0. For a document that selects titel instead of title it printed src/bad.ts, then 6:7 error Cannot query field "titel" on type "Product". Did you mean "title"?, and exited 1, which is what a CI step needs. The React Router template runs the check as part of its typecheck script.

Source: Shopify: Typed queries and validation

A Shopify storefront answers more than page requests: browser scripts call the Storefront API through the storefront’s own origin, apps link to cart permalinks, customers follow checkout links and old Liquid URLs need to redirect. Hydrogen’s request handlers restore these routes so that apps, analytics and agents integrate with a headless storefront the way they do with a theme. Two functions are wired around the framework’s router: handleShopifyRoutes() answers Shopify-owned routes before the router runs, and handleShopifyRedirects() checks for Shopify redirects after the router returns a 404.

handleShopifyRoutes() answers these routes:

Source: Shopify: Wire Hydrogen request handlers

handleShopifyRedirects() handles /admin (redirected to the store’s Shopify admin), Shopify’s standard storefront paths when route templates map them to the app’s paths, the URL redirects the merchant configured in the admin, and same-origin redirects from query parameters. It can make a Storefront API request, so it runs only after a 404. Checkout and cart permalink redirects outside / default to payment=shop_pay; an incoming payment parameter overrides it.

The Pocket Coffee request handler, written once and called from the framework’s entry point (a root middleware in React Router, proxy.ts in Next.js 16, server middleware in Nuxt). It wires the route templates, the cart handlers and the customer account handlers (registered after the customer account section):

Source: Shopify: Wire Hydrogen request handlers

The route templates manifest is a typed object that lists only the paths where the app differs from Shopify’s standard ones; an empty manifest is valid but must exist so there is one place to change later:

Source: Shopify: Configure route templates

The keys are product, productInCollection, collection, collectionList, page, policy, blog, article, cart and search. The placeholders are :productHandle, :collectionHandle, :pageHandle, :policyHandle, :blogHandle and :articleHandle; values are plain strings, without query strings, hashes or market prefixes (Hydrogen adds the prefix from the request context’s i18n.pathPrefix).

Hydrogen’s routing was exercised locally. With fetch stubbed (so no request left the machine), a request context for https://pocket-coffee.example.com, an empty route manifest and the cart handlers registered, handleShopifyRoutes() answered the following (the status and location lines are the observed output):

Source: Shopify: Verify your wiring

The same checks are the manual verification of a real deployment: curl -i -X POST http://localhost:<port>/api/2026-10/graphql.json with a public token header must return Storefront API JSON and not the framework’s 404, curl -i http://localhost:<port>/api/cart must return {"cart":null}, /admin must redirect to the store’s admin, and a nonexistent path must reach the framework’s 404 page unless the merchant configured a URL redirect for it. Do not narrow a Next.js proxy matcher to a list of Hydrogen paths: the list goes stale when Hydrogen adds routes. Register the handlers in the production server code, not in a development-only hook; only /graphiql is limited to development.

Hydrogen’s cart is a client-side store that stays in sync with the Shopify cart, with optimistic updates, pending state and errors scoped to the line, discount code, note or attribute that caused them. It has three parts: the server handlers from createCartServerHandlers() (the /api/cart endpoint, registered through handleShopifyRoutes()), the cart store in the browser (createCartStore(), or createCartComponents() for React and Vue), and cart forms (plain <form> elements whose fields and submit buttons come from the store’s register() helper, which encodes the cart action contract).

When a buyer submits a cart form: the store dispatches a Shopify standard action (an event such as shopify:cart:lines-update, shopify:cart:discount-update, shopify:cart:note-update or shopify:cart:attributes-update), applies an optimistic projection so the interface changes at once, records the affected line, code, note or attribute list as pending, calls /api/cart (which calls the Storefront API), and then folds the response into the confirmed state; on failure only the failed projection is rolled back and a scoped error is recorded. Because cart changes flow through the standard actions, installed apps, analytics and agents that use the same events stay in sync without extra wiring.

Source: Shopify: About the Hydrogen cart

The store exposes plain data you render from:

Source: Shopify: About the Hydrogen cart

The behaviours to design around:

A framework-neutral subscription, with the stub data that the local check used (the store was created in Node.js and read through getState(); submitting a form needs the browser’s window.Shopify.actions, so mutations were not run):

Source: Shopify: About the Hydrogen cart

With an initialData holding a cart of two units of PC-ETH-WHL-250 the store reported totalQuantity: 2, an empty pending.lines set and pending.note equal to false, and exposed the methods connect, destroy, hydrate, getState, subscribe, fetch, refresh, reset and handleFormSubmit. The state has the keys data, loading, pending and errors. In React and Vue, useCart comes from createCartComponents(); keep selectors stable (select primitives or existing references such as state.errors and state.data.lines.nodes), because hooks compare selector results by reference and a selector that builds a new array on each call re-renders on every update.

Hydrogen also gives collection, product form and predictive search stores in the same style, formatMoney() for money that comes from either API (it formats an object with amount and currencyCode for the customer’s locale and currency), Shop Pay buttons, and analytics with consent: Hydrogen 2026-10 removes Analytics.Provider, useAnalytics() and getShopAnalytics() in favour of rendering ShopifyScripts from @shopify/hydrogen/react in the root layout and publishing events to window.Shopify.analytics. Consent controls which events reach destinations, so migrate consent and analytics together. A sitemap is the app’s own code now (getSitemap() and getSeoMeta() are gone): query sitemap with storefront.graphql() and return the XML yourself.

Hydrogen does not decide how a storefront picks a market: subdomains, per-market domains, path prefixes, cookies or a saved preference are all valid. Its part is the request context: resolve the market once per request on the server, pass it as i18n (uppercase codes such as ES, US, EN) and let the client fill $country and $language. The pathPrefix is added to the URLs Hydrogen builds. Keep Shopify’s browser scripts and the links of the page in the same market, and follow the Markets page rule that prices are read, never computed. On Oxygen the oxygen-buyer-country header and its siblings (region, city, postal code, continent, time zone, oxygen-buyer-is-eu-country) are approximate and suited for suggesting a market, not for imposing one.

Hydrogen ships a guide and an agent skill (migrate-to-hydrogen-2026-10) for storefronts on 2026-04 or earlier. The steps, in order: check where the storefront starts, update dependencies (Node.js 22.12 or later, or 24), update scripts (plain Vite and React Router commands), update the Vite config (add the oxygen() MiniOxygen plugin before the framework’s), add a React Router config (future.v8_middleware: true on React Router 7), wire Hydrogen into the app (environment context, a simplified server.ts, the Storefront API client, route templates, cart handlers, a session manager and a root middleware), update routes and imports, update types and GraphQL, connect the store, migrate the features in the order markets, customer accounts, analytics and consent, then the cart, product pages, collection and search pages and Shop Pay, and finally check the migration. Where classic Hydrogen used context.storefront.query(), the new code uses storefrontClient.graphql() from a typed router context; createHydrogenContext() becomes the root middleware; and <Image>, <Money>, <Pagination> and <MediaFile> become the app’s own components. Features such as subscriptions, B2B, content pages, gift cards and product recommendations are the app’s code and migrate like any route.

Source: Shopify: Migrate to the latest version of Hydrogen

Source: Shopify: Oxygen runtime

The Worker is a module with a fetch function that receives the request, the environment bindings and an execution context. It must open the cache and bind waitUntil for each request, then hand control to the framework. The path server.ts at the project root is found by Oxygen and MiniOxygen without configuration (pass entry to the MiniOxygen plugin and --entry to the CLI commands otherwise):

Source: Shopify: Create the Worker entry point

The environment context types the variables the app reads (the template defines it in app/lib/env.ts):

Source: Shopify: Environment context

Pass the cache and waitUntil to the client together (createStorefrontClient({type: 'private', requestContext, config: {storeDomain, privateStorefrontToken, cache, waitUntil}})) so that cached queries can revalidate in the background after the response is sent. Hydrogen clients accept the Cache from caches.open() directly: do not wrap it in an adapter and do not use a process-local cache such as lru-cache, which does not survive across Worker instances.

Install MiniOxygen 4.2.0 or later and the Worker types, and add the oxygen() plugin to the Vite config before the framework’s plugin:

Source: Shopify: Configure MiniOxygen

The ssr.optimizeDeps list prevents CommonJS errors such as module is not defined when React Router runs in MiniOxygen. Replace Node-only code: for React Router, render with renderToReadableStream instead of renderToPipeableStream and remove @react-router/node and @react-router/serve. MiniOxygen loads variables from the .env files and passes them to the Worker’s env argument.

Source: Shopify: Build and preview

The build must produce one bundled Worker module (no code splitting of the server build) and a client assets directory: dist/client and dist/server/index.js with the default Vite layout. --worker-dir must contain index.js or index.mjs. Run npm run preview and request pages that use Hydrogen data (a product page, a collection page, /search, /cart, /account): a server that starts is not evidence that the Worker handles requests. The shopify hydrogen deploy command of CLI 5.0.0 builds and deploys, needs an Oxygen deployment token in --token or SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN (or uses the token of the linked storefront), and has these flags among others: --env or --env-branch to target an environment, --env-file, --preview to deploy to the Preview environment, --force (deploy with uncommitted changes and skip confirmation on non-preview environments), --no-verify (skip the routability check after deploying), --auth-bypass-token and --auth-bypass-token-duration (an authentication bypass token for end-to-end tests, up to 12 hours, 2 by default), --build-command, --assets-dir, --worker-dir, --metadata-description, --metadata-user, --json-output and --shop.

In the Shopify admin the Hydrogen channel contains storefronts; each storefront has environments, and each environment has deployments. A storefront links to one app. A deployment is an immutable snapshot, usually one Git commit.

Source: Shopify: Manage Oxygen environments and variables

Production and Preview are required and cannot be deleted. Each environment except Preview has a generated URL pointing to its most recent deployment, and can be rolled back to an earlier deployment without redeploying anything (the earlier deployment keeps the variables it was deployed with, which may be outdated). Environments are private by default: a buyer needs a store login to open one, and private URLs load more slowly because Oxygen verifies authentication on each request. A public environment is visible to anyone with the URL. The number of public environments depends on the plan:

Retail, nonprofit and custom plans also include one public environment.

Source: Shopify: Public environment limits

Each environment can have up to 110 environment variables, and a variable can have a different value per environment. Oxygen passes them to the Worker as the env argument on every request (not process.env). Shopify creates and manages these when a storefront is created:

Source: Shopify: Environment variables

Without PRIVATE_STOREFRONT_API_TOKEN the React Router template reads demo data from mock.shop; MOCK_SHOP=1 forces mock.shop in an environment that has a token. Deployments keep the variable values they had when deployed: after changing a variable, redeploy the environments that use it (the admin offers to). To use the variables locally, run npx shopify hydrogen env pull. Custom variables can be marked secret, which hides the value after saving.

To rotate the private Storefront API token: in Storefront settings > Storefront API choose Generate new token, update any other app that uses the token, deploy the storefront again (Oxygen does not redeploy environments when a token rotates), then revoke and delete the old token.

GitHub continuous deployment adds a workflow file .github/workflows/oxygen-deployment-<storefront_id>.yml. Leave the #! oxygen_storefront_id line alone, because it links the workflow to the storefront. The workflow uses npm and expects a package-lock.json (edit the install, cache and build steps for another package manager), and it reads the deployment token from the repository secret OXYGEN_DEPLOYMENT_TOKEN_<storefront_id>, passed to the CLI as SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN. To deploy from another system (GitLab, Bitbucket, CircleCI), create an Oxygen deployment token in Storefront settings > Oxygen deployments (valid for one year; one per service), store it as SHOPIFY_HYDROGEN_DEPLOYMENT_TOKEN and run:

Source: Shopify: Continuous deployment

Deployments are private until a share link is created (the Basic plan or higher can create an "anyone with the link" link that carries a token bypassing the login; Oxygen adds a disallow rule to the robots.txt of shared deployments, and a change to a link takes up to 30 seconds). Deployments stay available for at least six months; the ten most recent deployments of each environment are always kept, and runtime logs are available for up to one month. The generic deployment pipeline (security checks, secrets, release flow) is the subject of the billing, App Store and deployment page; this page covers only what is specific to Oxygen.

Wherever the storefront is deployed, a Hydrogen storefront needs the same five things from its runtime: request-scoped state (create the request context, clients and session managers inside each request; only pure constants such as handler groups and route templates may live at module scope), server-only secrets (read from the host’s bindings, not process.env, where the host passes bindings), a trusted buyer IP, a cache and waitUntil for the client, and the request handlers wired in production server code. The Next.js starter (Vercel Shop, Next.js 16 with the App Router, deployed to Vercel) is the reference for a non-Oxygen host: its proxy.ts replaces middleware.ts and forwards the original URL in the x-storefront-url header, and it keeps the proxy matcher broad. Before any deployment, run the production checklist: the static checks (formatter, lint or type check, hydrogen gql check, build, tests), the request handler curls shown earlier, every header and footer link (/collections/all does not exist in the Storefront API unless the store has a collection with the handle all), the signed-out customer account states, product pages (variant selection from the URL, sold-out values selectable and disabled combinations that do not exist) and the cart (/cart works without JavaScript and the drawer opens from window.Shopify.actions.openCart()).

Source: Shopify: Getting started with the Customer Account API

Web callback URLs must use HTTPS, mobile callback URLs must use the custom scheme shop.{shop_id}.*, and Shopify does not support localhost or any http URL because of the OAuth for native apps guidance (RFC 8252): use a tunnelling service such as ngrok, or Hydrogen’s trusted local HTTPS. The Customer Account API scopes (the customer_* scopes) are listed on the access scopes page; for Headless and Hydrogen they are set in the channel, and the usual scope string in the authorization request is openid email customer-account-api:full.

The flow is OAuth 2.0 authorization code, with OpenID Connect for the ID token, and PKCE for public clients.

Source: Shopify: Customer Account API reference

Both discovery endpoints are on the storefront domain, so a client works with any shop configuration and does not hard-code Shopify’s domains: GET /.well-known/openid-configuration returns authorization_endpoint, token_endpoint, end_session_endpoint and jwks_uri, and GET /.well-known/customer-account-api returns graphql_api (a URL of the form https://<customer accounts domain>/customer/api/<latest version>/graphql, which may be a vanity domain) and mcp_api. Discover once at the beginning of the flow and reuse the endpoints.

The authorization request parameters:

Source: Shopify: Authorization

The PKCE helpers and the authorization URL builder below were run in Node.js 24 with placeholder endpoints (the discovery document is a literal, because discovery needs a store). The verifier is 32 random bytes, base64url encoded (43 characters), the challenge is the SHA-256 of the verifier, base64url encoded without padding, and the state and nonce are random UUIDs:

Source: Shopify: Code challenge and verifier

The check against the RFC 7636 appendix B test vector (dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk must give E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM) printed true. The URL built for Pocket Coffee carried the parameters scope, client_id, response_type, redirect_uri, state, nonce, code_challenge, code_challenge_method, locale, region_country, and a verifier of 43 base64url characters. Shopify’s reference code uses Math.random() for the state and the nonce; use a cryptographically secure source, as above.

The token request is a POST with application/x-www-form-urlencoded to the discovered token_endpoint:

The response has access_token, id_token and expires_in (seconds), and a refresh_token for the customer account clients configured on the shop (Headless and Hydrogen storefronts). The refresh request is the same POST with grant_type=refresh_token, client_id and the refresh_token (plus the Authorization header for confidential clients) and returns a new access token and refresh token. Apps that authenticate with their own app client ID through the customer_authentication app configuration are public clients that do not receive refresh tokens: the refresh_token grant returns 400 with unsupported_grant_type, and a new token is obtained by repeating the code flow with prompt=none from a top-level navigation (the authorization endpoint cannot be loaded in an iframe).

Source: Shopify: Obtain access token

To log out, redirect the buyer to the discovered end_session_endpoint with id_token_hint (the id_token received at login, required) and post_logout_redirect_uri (optional; otherwise one of the registered logout URLs). A mobile client calls the endpoint as an API and gets 200 OK instead of a redirect.

The Customer Account API is rate limited by calculated query cost: a quota of 7,500 cost points per app, per store and customer, refilled as a leaky bucket at 100 points per second (Standard), 200 points per second (Advanced Shopify and Shopify Plus) or 400 points per second (Shopify for enterprise). Most fields cost 1 point and most mutations cost 10; every response reports requestedQueryCost and actualQueryCost under extensions, and the header Shopify-GraphQL-Cost-Debug: 1 returns a per-field breakdown. Separately, requests of all apps for one customer on one store share 3,000 requests per minute in a fixed 60-second window: above it the API returns HTTP 429 with a THROTTLED error and a Retry-After header. Exceeding the cost quota returns 200 OK with THROTTLED.

A buyer’s profile and latest orders, plus a profile update, validated against the schema shipped with Hydrogen (the 2026-10 Customer Account endpoint of shopify.dev’s introspection proxy is not published, so the packaged schema is the reference used; it matches what the Hydrogen client sends):

Source: Shopify: customer query

The request is a POST to the graphql_api URL from discovery with the header Authorization: <access_token> (the access token itself, with no Bearer prefix, as in Shopify’s examples) and a JSON body with the query. Pocket Coffee reads tags to show the Coffee Club badge to members, because the Coffee Club group is implemented as a customer tag on the Admin side.

Hydrogen provides the client (createCustomerAccountClient()), the OAuth route handlers and the session helpers; the app owns where the tokens are stored and the account interface. The flow is: a link to /account/login, Hydrogen redirects to Shopify’s hosted login, Shopify redirects back to /account/authorize where Hydrogen exchanges the code for tokens and stores them in the session, the server reads the access token from the session and queries the API, /account/refresh renews an expired token and a POST to /account/logout ends the session. The four routes are owned by handleShopifyRoutes(), so the app writes no login, authorize, refresh or logout logic and deletes any route files for those paths. Link to them with plain <a> and <form> elements, not the framework’s client-side Link or Form, so the request reaches the server.

Requirements: a real store (mock.shop has no Customer Account API), the request handlers and a Storefront API client wired, and an HTTPS origin on a host other than localhost. The variables:

Source: Shopify: Configure the Customer Account API

In the client’s settings choose Public (web app) and register the callback URI (the storefront origin plus /account/authorize), the JavaScript origin and the logout URI. Then create the customer session once at module scope (concurrent token refreshes for one customer then share one request) and a session manager per request. A session manager is an object with getSessionOrigin(), getSessionItem(), setSessionItem(), removeSessionItem() and an optional commit() that returns the Set-Cookie headers; back it with protected server storage or an HttpOnly cookie and never put tokens in browser storage or in client components.

Source: Shopify: Create the customer session

Source: Shopify: Sync cart buyer identity

Behaviour to rely on:

The account page loads the customer with the token and the validated query above:

Source: Shopify: Build the account page

The sign-out control must be a native form (<form method="post" action="/account/logout">), because the logout handler accepts only same-origin POST requests and answers with a redirect that only a native form submission follows.

Signing in locally. Login, logout and callbacks need an HTTPS origin that is not localhost and exactly matches the URLs registered in the admin. local.tryhydrogen.dev is a Shopify-owned domain that resolves to 127.0.0.1, so it is a stable local host name. The localHttps() Vite plugin of @shopify/hydrogen/vite (enabled only for a dev:https script) installs a checksum-verified release of mkcert, creates a local certificate authority and writes certificates to ~/.shopify/hydrogen/certs/; npx hydrogen certs install does it ahead of time (needed with CI=true), npx hydrogen certs uninstall removes the certificates (add --remove-ca to also remove the authority), and the plugin registers the local URLs in the Customer Account API settings through Shopify CLI with @shopify/cli-hydrogen 13.0.4 or later. If registration fails, add the URLs by hand. shopify hydrogen customer-account-push pushes a development origin to the admin from the command line.

Shopify announced on 2026-02-26 that legacy customer accounts are deprecated: they are unavailable to new stores and to stores that do not use them, receive no feature updates or support, and "a final sunset date will be announced later in 2026" (no date had been announced at the check date). Themes should drop the legacy customer account Liquid files and use the shopify-account web component, and custom storefronts should use the Customer Account API instead of the Storefront API’s customer-scoped operations. In the 2026-10 Storefront schema, customerAccessTokenCreate (documented as "for legacy customer accounts only"), customerAccessTokenRenew, customerAccessTokenDelete, customerCreate, customerUpdate, customerRecover, the address mutations and the customer query still exist and are not marked deprecated in the schema, so code that uses them keeps working until the sunset; new storefronts should not start there.

The Customer Account API schema contains a mutation storefrontCustomerAccessTokenCreate, which exchanges the Customer Access Token sent in the Authorization header into a Storefront customer access token (to be renewed each time the Customer Access Token is updated). Code that still needs the Storefront customer fields can use it as a bridge while it migrates.