Skip to main content
Live with caveats. This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.

​
Goal

Connect a headless storefront while keeping Shopify as the commerce backend and credentials isolated by target.

​
Prerequisites

  • A GitHub-connected Hydrogen or Storefront API project
  • A Shopify store with the Headless sales channel and Storefront API permissions
  • A production-capable Node start command

​
Workflow

1
Install or open the Headless sales channel in Shopify admin and create the storefront identities and tokens required for each target.
2
Connect the StackShift project as kind storefront using the canonical *.myshopify.com store domain.
3
For a non-Hydrogen Node storefront, explicitly confirm generic storefront hosting.
4
Save at least one Storefront API token for development, production, and preview, then verify each target.
5
Deploy branches to generated URLs before adding an optional production custom domain.

​
Get Storefront API credentials

Shopify’s current setup is documented in Getting started with the Storefront API. In Shopify admin, install or open the Headless sales channel, create a storefront, choose its Storefront API permissions, and copy the generated public and private tokens. Use separate storefront/token records per StackShift target where your Shopify operating model requires strict environment separation. StackShift accepts either a public or a private token and uses the private token when both are present.
  • Public token verification sends X-Shopify-Storefront-Access-Token.
  • Private token verification sends Shopify-Storefront-Private-Token.
  • Verification calls https://<store_domain>/api/<configured-version>/graphql.json with a minimal shop-name query.
  • A Storefront API token belongs to the store. An app client secret or Admin API access token is not a substitute.

​
Optional Customer Account API

  • Customer Account configuration is optional. If any Customer Account field is supplied, the client ID becomes required.
  • Supply the customer account client ID, optional secret, and the HTTPS Customer Account API URL used by the storefront. URLs with user information, query strings, fragments, or a non-443 explicit port are rejected.
  • StackShift queries the connected store domain’s OpenID and Customer Account API well-known documents and requires secure authorization and GraphQL endpoints.
  • The discovery check proves endpoint configuration; it does not perform an end-user login or cryptographically exercise the optional customer secret.

​
Target and runtime isolation

  • Storefronts have development, production, and preview credential records.
  • The primary GitHub branch uses production credentials. Any non-primary storefront branch uses preview credentials.
  • Runtime variables can include PUBLIC_STORE_DOMAIN, SHOPIFY_APP_URL, public/private Storefront API tokens, storefront ID, and Customer Account client fields.
  • Secrets are injected only into the selected runtime target and are never returned by the Shopify API after save.

​
Hydrogen runtime requirement

StackShift does not run Shopify Oxygen. A Hydrogen repository must expose a Node production server: an Express or React Router Express dependency, source signals for createRequestHandler and Express, and a production start script. A Hydrogen project that only has an Oxygen adapter is rejected before connection.

​
Expected result

The storefront has development, production, and preview target records with verified Storefront API access and no Shopify secret committed to source.

​
Common failures

  • An Admin API token was entered instead of a Storefront API token
  • The token belongs to another store or lacks Storefront API permissions
  • The project is Hydrogen but has no supported Node adapter/start command
  • Generic Node hosting was not explicitly confirmed
  • Customer Account discovery URL is not a clean HTTPS origin or does not expose secure endpoints

Shopify hosting overview

What StackShift hosts, what remains in Shopify, who supplies credentials, and how app and storefront hosting differ.

Storefront previews, promotion, and domains

Test on generated URLs and promote an active preview’s exact immutable image to production without rebuilding it.

Storefront cache, analytics, and Shop Pay

Configure commerce-safe caching, inspect storefront traffic and checkout redirects, and gate optional Shop Pay activation.