Add subscribe-and-save

This tutorial adds subscriptions to a storefront you already have — for example the one from Build a storefront from scratch. Subscriptions on Flightdeck are a real recurring-billing engine (a schedule, an exactly-once renewal sweep, a dunning ladder). You do not run any of that; you opt a shopper in at checkout with proper consent, and the platform bills on the schedule. Your job on the storefront is three things: render the auto-renewal disclosure, send the consent block with the order, and honor the reminders.

Prerequisites: the manifest gate

Subscribe-and-save is off unless the store’s manifest enables it. Two behavior keys gate the surfaces you are about to build:

• behavior.subscriptions.enabled — the Subscribe & Save switch. Default false. behavior.subscriptions.discounts maps interval-days ("30", "60") to a percent off, and behavior.subscriptions.autoEnrollBundles defaults false.
• behavior.accounts.subscriptionSelfServe — the account-page self-serve cancel/pause surface. Defaults true.

These are set operator-side / through the site builder, not the storefront SDK. Read the active manifest with store.site.get() and gate your UI on it — do not show a Subscribe control the backend will refuse.

How a subscription is created

There is no separate “create subscription” storefront call. A subscription is created as part of an order by passing subscribe: true in the checkout body. The platform starts a subscription for every subscription-eligible line in that order.

Two things are non-negotiable when subscribe: true originates from a storefront:

1. You must render the auto-renewal disclosure to the shopper before the opt-in control.
2. The request must carry a subscriptionConsent block proving they saw it.

Without recorded consent evidence the checkout is refused with 400 subscription_consent_required.

The consent block

subscriptionConsent: {
  disclosureRef: "arl-disclosure-v1",   // the disclosure VERSION the shopper saw
  disclosureSha256: "<hex>",            // SHA-256 of the rendered disclosure text
  ipHash?: "<hex>",                     // optional: SHA-256 of the shopper IP
  userAgent?: "<ua string>",            // optional
}

Build the flow

const manifest = await store.site.get();
const subsEnabled = manifest.behavior?.subscriptions?.enabled === true;
// Only render the Subscribe & Save opt-in when subsEnabled is true.

"use client";
import { useState } from "react";
 
// The exact text the shopper sees. Bump DISCLOSURE_REF when this text changes.
export const DISCLOSURE_REF = "arl-disclosure-v1";
export const DISCLOSURE_TEXT =
  "By subscribing, you authorize recurring charges at the interval shown until you cancel. " +
  "We will email you a reminder before each renewal. Cancel anytime from your account.";
 
export function SubscribeConsent({ onChange }: { onChange: (optIn: boolean) => void }) {
  const [checked, setChecked] = useState(false);
  return (
    <fieldset>
      {/* Disclosure FIRST, opt-in control SECOND. */}
      <p>{DISCLOSURE_TEXT}</p>
      <label>
        <input
          type="checkbox"
          checked={checked}
          onChange={(e) => { setChecked(e.target.checked); onChange(e.target.checked); }}
        />
        Subscribe and save
      </label>
    </fieldset>
  );
}

import { createHash } from "node:crypto";
import { DISCLOSURE_REF, DISCLOSURE_TEXT } from "@/components/subscribe-consent";
 
const disclosureSha256 = createHash("sha256").update(DISCLOSURE_TEXT).digest("hex");

const result = await store.checkout.submit(
  {
    customer_ref: `guest:${email}`,
    email,
    items,
    card,
    subscribe: true, // start a subscription for every eligible line
    // Enforced at the route; not in the generated types yet.
    subscriptionConsent: {
      disclosureRef: DISCLOSURE_REF,
      disclosureSha256,
      // Optional hardening — hash the BFF-forwarded shopper IP, pass the UA.
      // ipHash: createHash("sha256").update(shopperIp).digest("hex"),
      // userAgent: req.headers.get("user-agent") ?? undefined,
    },
  } as any, // consent block is not in the generated body type yet
  { idempotencyKey: `cart-${cartId}:attempt-1` },
);

// result.subscriptions: Array of…
// { id, plan_ref, interval, interval_count, unit_price_cents, currency, status, next_bill_at }
for (const sub of result.subscriptions) {
  // e.g. confirm "Renews every {interval_count} {interval} — next on {next_bill_at}"
  console.info(sub.id, sub.interval, sub.next_bill_at);
}

Renewal reminders — a legal obligation you inherit

Every store sends a pre-billing renewal reminder, and this is not optional. The renewal sweep covers active and past_due subscriptions.

• renewalReminderDaysBeforeBilling is per-store, default 7, with an enforced floor of 3. Values below the floor clamp to the default and are logged. Reminders cannot be configured off.
• Reminders are transactional: a shopper’s marketing unsubscribe never blocks them. A hard bounce records the reminder as undeliverable (visibly), never as sent.

For your storefront this means: the email you collect at checkout (email, which rides the order as customer_contact_email) is what the confirmation and the auto-renewal terms acknowledgment and every renewal reminder deliver to. Collect a real, deliverable address, and make the auto-renewal terms clear at opt-in — the platform enforces the reminder cadence, but the disclosure quality is yours.

Reading and managing subscription state

Here is the honest boundary. The storefront SDK (createStorefrontClient) does not wrap shopper subscription list/cancel/pause/resume today — those methods are not on the client, and the routes are not in the generated types. What you do get from the SDK is the subscriptions array on the checkout response above.

For ongoing management you have two real options:

// Server-side only — the storefront token authorizes this.
const res = await fetch(
  `${process.env.FLIGHTDECK_API_URL}/v1/tenants/${tenant}/customers/${encodeURIComponent(customerRef)}/subscriptions`,
  { headers: { "x-storefront-token": process.env.FLIGHTDECK_STOREFRONT_TOKEN! } },
);
if (!res.ok) throw new Error(`subscription read failed: ${res.status}`); // never swallow into []
const { subscriptions } = await res.json();

Recap

Related

• Checkout — the full submit body and the consent note.
• Subscriptions — the engine, routes, and manifest gates.
• Build a storefront from scratch — the storefront this builds on.
• SDK reference — the storefront client surface.