---
title: "Headless and Hydrogen storefronts"
description: "Run preorders and Notify me on a headless or Hydrogen storefront with the STOQ Storefront SDK."
url: https://help.stoqapp.com/general/headless-and-hydrogen-storefronts/
product: "General"
section: "Page builders and platforms"
last_updated: 2026-10-15
---

# Headless and Hydrogen storefronts

> Run preorders and Notify me on a headless or Hydrogen storefront with the STOQ Storefront SDK.

STOQ's preorder button and Notify me widget ship as a Shopify theme app embed, so they don't load on headless storefronts like Hydrogen, Next.js Commerce, or a custom build. The STOQ Storefront SDK brings the same features to those stacks: per-variant preorder state, cart lines with the right selling plan attached, and back in stock signups including the Notify me modal.

This is a developer task. For the full step-by-step guide, components, and API reference, see the [Headless and Hydrogen SDK docs](https://docs.stoqapp.com/sdk/docs/headless/).

## Before you begin

- The SDK authenticates with your shop's **public Storefront API access token**, the same one your headless store already uses. It identifies your shop by domain, so no secret key goes in storefront code.
- Never put your STOQ API key (the `X-Auth-Token` admin key) in browser or client-side code. The SDK never uses it. Keep that key for server-side calls to the [preorder](https://help.stoqapp.com/preorders/preorder-api/) and [back in stock](https://help.stoqapp.com/back-in-stock/back-in-stock-api/) APIs.

## Install the SDK

Pick the path that matches your stack.

- **Script tag (any stack).** Add one `<script>` tag to your `<head>` with `data-shop="your-shop.myshopify.com"` and `data-storefront-token="your-public-storefront-api-token"`. It defines a global `Stoq` and initializes on load.
- **npm (Hydrogen or React).** Install `@artossoftware/stoq-sdk`. React hooks and components live under the `@artossoftware/stoq-sdk/react` entry.

## What you get

- **Preorder state per variant.** Ask the SDK about a variant and branch on whether it's preorderable.
- **Preorder cart lines.** The SDK hands you a finished cart line with the correct selling plan attached, ready to pass to the Storefront API `cartLinesAdd`. STOQ takes over from the order webhook for payments, holds, and tagging.
- **Notify me.** Open the full modal with `Stoq.openModal`, or render it inline in your own element with `Stoq.openInlineForm`. Show the Notify me control when the variant isn't available for sale and signups are enabled.

## Good to know

If an offer is restricted to specific Shopify Markets, pass the market to the SDK. Without it, every variant on a market-scoped offer reports as not preorderable, so the store can look like it has no preorders at all. Global offers work without it.

## Related guides

- [Preorder API for developers](https://help.stoqapp.com/preorders/preorder-api/): Manage offers, variants, and orders from your own code.
- [Back in stock API for developers](https://help.stoqapp.com/back-in-stock/back-in-stock-api/): Build custom back in stock integrations with the same API key.