Headless and Hydrogen storefronts

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.

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 and back in stock 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 developersManage offers, variants, and orders from your own code.

Back in stock API for developersBuild custom back in stock integrations with the same API key.