> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure Shopify storefront hosting

> Connect Hydrogen or a confirmed Node storefront, obtain Storefront API credentials, isolate targets, and verify Shopify access.

<Warning>
  **Live with caveats.** This area is real and usable, but the docs intentionally call out operational or UX limits that still matter.
</Warning>

## 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

<Steps>
  <Step>
    Install or open the Headless sales channel in Shopify admin and create the storefront identities and tokens required for each target.
  </Step>

  <Step>
    Connect the StackShift project as kind `storefront` using the canonical `*.myshopify.com` store domain.
  </Step>

  <Step>
    For a non-Hydrogen Node storefront, explicitly confirm generic storefront hosting.
  </Step>

  <Step>
    Save at least one Storefront API token for development, production, and preview, then verify each target.
  </Step>

  <Step>
    Deploy branches to generated URLs before adding an optional production custom domain.
  </Step>
</Steps>

## Get Storefront API credentials

Shopify’s current setup is documented in [Getting started with the Storefront API](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/getting-started). 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

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

## Common failures

<Warning>
  * 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
</Warning>

## Related guides

<CardGroup cols={2}>
  <Card title="Shopify hosting overview" href="/shopify/overview">
    What StackShift hosts, what remains in Shopify, who supplies credentials, and how app and storefront hosting differ.
  </Card>

  <Card title="Storefront previews, promotion, and domains" href="/shopify/previews-promotion-and-domains">
    Test on generated URLs and promote an active preview’s exact immutable image to production without rebuilding it.
  </Card>

  <Card title="Storefront cache, analytics, and Shop Pay" href="/shopify/cache-analytics-and-shop-pay">
    Configure commerce-safe caching, inspect storefront traffic and checkout redirects, and gate optional Shop Pay activation.
  </Card>
</CardGroup>