BackInStockBro

Headless storefront SDK

Connect Hydrogen or another custom Shopify storefront to exact-variant availability notifications. The MIT-licensed SDK is available as version 0.1.0, an early release under the next tag.

Set up in Shopify Admin

  1. Open BackInStockBro → Headless.
  2. Register each exact HTTPS storefront origin, without a path.
  3. Create a publishable key and copy it once. Rotating it invalidates the old key.
  4. Keep Shopify Admin tokens and all management credentials on your server.

Install the SDK

View the official package on npm

npm install @brofam.app/backinstockbro-storefront@next

Client contract

import {createBackInStockBroClient} from '@brofam.app/backinstockbro-storefront';

const client = createBackInStockBroClient({
  endpoint: "https://public.backinstockbro.app",
  publishableKey
});
const preparation = await client.prepareNotification({
  productId, variantId
});

Product and variant IDs are Shopify GraphQL IDs. Read availability through Shopify's Storefront API; the SDK does not provide a product catalog.

Complete the request

Show the returned challenge URL in an iframe. Accept its verification message only from the returned challenge origin and that iframe's content window. Then call subscribe with the same product and variant, product handle, email, form token and challenge assertion. Preserve the selected variant while verification is in progress.

Endpoints: POST /storefront/v1/notifications/prepare and POST /storefront/v1/notifications. Both use the x-backinstockbro-key header. A publishable key identifies an installation; it grants no customer-read or Shopify Admin access.

What you build

Your storefront supplies its own form, variant selection and accessible success/error states. Theme availability tables and sticky controls are not automatically installed on a headless storefront. An accepted request does not guarantee email delivery: suppression and availability checks still apply.

Before launch

Test allowed and rejected origins, variant changes during verification, expired challenges, key revocation, one complete notification and opt-out. The package includes TypeScript types and a Hydrogen reference component at examples/hydrogen/BackInStockForm.tsx.

Get integration help