Subscriptions with hosted checkout (Next.js)

ZAHLO_API_KEY=zk_test_your_sandbox_key
ZAHLO_WEBHOOK_SECRET=set_in_step_6
SITE_URL=http://localhost:3000

// Creates the Pro plan, its monthly price with a 14-day trial, and a coupon, once per environment.
// Run: node --env-file=.env.local scripts/setup-catalog.mjs
// Safe to run again: it finds the price by lookupKey and the coupon by code, and creates nothing twice.
const apiKey = process.env.ZAHLO_API_KEY;
if (!apiKey) throw new Error("Set ZAHLO_API_KEY");
const apiBase =
  process.env.ZAHLO_API_BASE ??
  (apiKey.startsWith("zk_live_") ? "https://merchant.zahlo.eu" : "https://merchant-demo.zahlo.eu");

const PLAN = { lookupKey: "pro-monthly", name: "Pro", unitAmountMinor: 1900, trialDays: 14 };
const COUPON = { code: "WELCOME15", name: "15% off for 3 months", percentOff: 15, duration: "repeating", durationInMonths: 3 };

async function call(method, path, body, idempotencyKey) {
  for (let attempt = 0; ; attempt += 1) {
    const response = await fetch(`${apiBase}/api/v1${path}`, {
      body: body === undefined ? undefined : JSON.stringify(body),
      headers: {
        "content-type": "application/json",
        "x-api-key": apiKey,
        ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
      },
      method,
    });
    if (response.ok) return response.json();
    const error = (await response.json().catch(() => ({}))).error ?? {};
    const retry = response.status === 429 || response.status >= 500 || error.code === "request_in_progress";
    if (retry && attempt < 2) {
      await new Promise((resolve) => setTimeout(resolve, 1000 * 2 ** attempt));
      continue;
    }
    throw new Error(`${method} ${path} -> ${response.status} ${error.code}: ${error.message}`);
  }
}

async function listAll(path) {
  const items = [];
  for (let after = ""; ; ) {
    const page = await call("GET", `${path}?limit=100${after ? `&startingAfter=${after}` : ""}`);
    items.push(...page.data);
    if (!page.hasMore || page.data.length === 0) return items;
    after = page.data.at(-1).id;
  }
}

const prices = await listAll("/prices");
if (prices.some((price) => price.active && price.lookupKey === PLAN.lookupKey)) {
  console.log(`price ${PLAN.lookupKey}: exists`);
} else {
  const product = await call("POST", "/products", { name: PLAN.name }, `setup-product-${PLAN.lookupKey}`);
  await call(
    "POST",
    "/prices",
    {
      currency: "EUR",
      lookupKey: PLAN.lookupKey,
      productId: product.id,
      recurring: { interval: "month", trialDays: PLAN.trialDays },
      type: "recurring",
      unitAmountMinor: PLAN.unitAmountMinor,
    },
    `setup-price-${PLAN.lookupKey}`
  );
  console.log(`price ${PLAN.lookupKey}: created`);
}

const coupons = await listAll("/coupons");
if (coupons.some((coupon) => coupon.code === COUPON.code)) {
  console.log(`coupon ${COUPON.code}: exists`);
} else {
  await call("POST", "/coupons", COUPON, `setup-coupon-${COUPON.code}`);
  console.log(`coupon ${COUPON.code}: created`);
}

// Server-only Zahlo API client. Never import this file from a client component.
const apiKey = process.env.ZAHLO_API_KEY ?? "";

/** zk_test_ keys use the sandbox, zk_live_ keys use live. */
export const apiBase =
  process.env.ZAHLO_API_BASE ??
  (apiKey.startsWith("zk_live_")
    ? "https://merchant.zahlo.eu"
    : "https://merchant-demo.zahlo.eu");

export class ZahloError extends Error {
  constructor(
    readonly status: number,
    readonly code: string,
    message: string,
    readonly requestId: string | null
  ) {
    super(message);
  }
}

const MAX_RETRIES = 2;
const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
const backoff = (attempt: number, response?: Response) =>
  Number(response?.headers.get("retry-after") ?? 0) * 1000 ||
  500 * 2 ** attempt;

/** Retry only what can succeed on a second try: network errors, 409 request_in_progress, 429 and 5xx. */
const retryable = (status: number, code: string) =>
  status === 429 ||
  status >= 500 ||
  (status === 409 && code === "request_in_progress");

/**
 * Calls the Zahlo API. Every POST carries one Idempotency-Key, reused on each retry,
 * so a retried request can never create a second object.
 */
export async function zahlo<T>(
  method: "GET" | "POST" | "PATCH" | "DELETE",
  path: string,
  options: { body?: unknown; idempotencyKey?: string } = {}
): Promise<T> {
  const idempotencyKey =
    method === "POST"
      ? (options.idempotencyKey ?? crypto.randomUUID())
      : undefined;
  for (let attempt = 0; ; attempt += 1) {
    let response: Response;
    try {
      response = await fetch(`${apiBase}/api/v1${path}`, {
        body:
          options.body === undefined ? undefined : JSON.stringify(options.body),
        headers: {
          "content-type": "application/json",
          "x-api-key": apiKey,
          ...(idempotencyKey ? { "idempotency-key": idempotencyKey } : {}),
        },
        method,
        signal: AbortSignal.timeout(15_000),
      });
    } catch (error) {
      if (attempt < MAX_RETRIES) {
        await sleep(backoff(attempt));
        continue;
      }
      throw error;
    }
    if (response.ok) {
      return (response.status === 204 ? undefined : await response.json()) as T;
    }
    const payload = await response.json().catch(() => ({}));
    const code: string = payload?.error?.code ?? "unknown";
    if (attempt < MAX_RETRIES && retryable(response.status, code)) {
      await sleep(backoff(attempt, response));
      continue;
    }
    throw new ZahloError(
      response.status,
      code,
      payload?.error?.message ?? response.statusText,
      payload?.error?.requestId ?? response.headers.get("x-request-id")
    );
  }
}

/** Lists return one page at a time; follow startingAfter until hasMore is false. */
export async function listAll<T extends { id: string }>(
  path: string
): Promise<T[]> {
  const items: T[] = [];
  let startingAfter = "";
  for (;;) {
    const page = await zahlo<{ data: T[]; hasMore: boolean }>(
      "GET",
      `${path}?limit=100${startingAfter ? `&startingAfter=${startingAfter}` : ""}`
    );
    items.push(...page.data);
    const last = page.data.at(-1);
    if (!(page.hasMore && last)) {
      return items;
    }
    startingAfter = last.id;
  }
}

import { DatabaseSync } from "node:sqlite";

// Any database with transactions works; SQLite keeps the quickstart self-contained.
export const db = new DatabaseSync(process.env.DATABASE_PATH ?? "app.db");

db.exec(`
  CREATE TABLE IF NOT EXISTS users (
    id TEXT PRIMARY KEY,
    email TEXT NOT NULL UNIQUE,
    subscription_id TEXT UNIQUE,
    subscription_status TEXT,      -- trialing | active | past_due | paused | cancelled | incomplete
    past_due_since TEXT,
    current_period_end TEXT
  );
  CREATE TABLE IF NOT EXISTS processed_events (
    event_id TEXT PRIMARY KEY,
    processed_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
  );
`);

/** Runs fn in one transaction: all of its writes commit together, or none do. */
export function transaction<T>(fn: () => T): T {
  db.exec("BEGIN IMMEDIATE");
  try {
    const result = fn();
    db.exec("COMMIT");
    return result;
  } catch (error) {
    db.exec("ROLLBACK");
    throw error;
  }
}

export type User = {
  id: string;
  email: string;
  subscription_id: string | null;
  subscription_status: string | null;
  past_due_since: string | null;
  current_period_end: string | null;
};

import { db, type User } from "./db";

// Stand-in for your auth library (Auth.js, Clerk, your own sessions). The quickstart signs in by email
// and keeps the user id in a cookie; replace both functions with your real sign-in.
export function userFromRequest(request: Request): User | null {
  const id = /(?:^|;\s*)uid=([^;]+)/.exec(request.headers.get("cookie") ?? "")?.[1];
  if (!id) return null;
  return (db.prepare("SELECT * FROM users WHERE id = ?").get(decodeURIComponent(id)) as User | undefined) ?? null;
}

export function signIn(email: string): User {
  db.prepare("INSERT INTO users (id, email) VALUES (?, ?) ON CONFLICT (email) DO NOTHING").run(
    crypto.randomUUID(),
    email.trim().toLowerCase()
  );
  return db.prepare("SELECT * FROM users WHERE email = ?").get(email.trim().toLowerCase()) as User;
}

import { signIn } from "../../../lib/auth";

// Demo sign-in: replace with your auth library.
export async function POST(request: Request) {
  const user = signIn(String((await request.formData()).get("email") ?? ""));
  return new Response(null, {
    headers: { location: "/account", "set-cookie": `uid=${user.id}; Path=/; HttpOnly; SameSite=Lax` },
    status: 303,
  });
}

import { type User } from "./db";
import { listAll, zahlo } from "./zahlo";

type Price = { id: string; lookupKey: string | null; active: boolean };
type Coupon = { id: string; code: string | null; active: boolean };
export type CheckoutSession = {
  id: string;
  type: "payment" | "subscription";
  url: string | null;
  clientToken: string | null;
  status: "open" | "complete" | "expired" | "failed";
  subscriptionId: string | null;
  reference: string | null;
};

const siteUrl = process.env.SITE_URL ?? "http://localhost:3000";

/** Starts a subscription checkout for the signed-in user. The price is found by lookupKey. */
export async function createSubscriptionSession(
  user: User,
  options: { mode: "hosted" | "embedded"; promoCode?: string }
): Promise<CheckoutSession> {
  const prices = await listAll<Price>("/prices");
  const price = prices.find((p) => p.active && p.lookupKey === "pro-monthly");
  if (!price) throw new Error("No price with lookupKey pro-monthly; run scripts/setup-catalog.mjs");
  let couponId: string | undefined;
  if (options.promoCode) {
    const coupons = await listAll<Coupon>("/coupons");
    couponId = coupons.find(
      (c) => c.active && c.code?.toUpperCase() === options.promoCode?.toUpperCase()
    )?.id;
  }
  return zahlo<CheckoutSession>("POST", "/checkout-sessions", {
    // One key per attempt; a network retry inside zahlo() reuses it.
    idempotencyKey: `subscribe-${user.id}-${crypto.randomUUID()}`,
    body: {
      type: "subscription",
      mode: options.mode,
      lineItems: [{ priceId: price.id, quantity: 1 }],
      couponId,
      customerEmail: user.email,
      reference: user.id,
      successUrl: `${siteUrl}/account?session_id={CHECKOUT_SESSION_ID}`,
      cancelUrl: `${siteUrl}/account`,
    },
  });
}

import { userFromRequest } from "../../../lib/auth";
import { createSubscriptionSession } from "../../../lib/subscribe";
import { ZahloError } from "../../../lib/zahlo";

// Hosted checkout: create the session on the server, then send the browser to session.url.
export async function POST(request: Request) {
  const user = userFromRequest(request);
  if (!user) return new Response("Sign in first", { status: 401 });
  const promoCode = String((await request.formData()).get("promoCode") ?? "").trim() || undefined;
  try {
    const session = await createSubscriptionSession(user, { mode: "hosted", promoCode });
    return Response.redirect(session.url ?? "", 303);
  } catch (error) {
    if (error instanceof ZahloError) {
      console.error("subscribe failed", error.code, error.requestId);
      return new Response(error.message, { status: error.status >= 500 ? 502 : 400 });
    }
    throw error;
  }
}

import { type User } from "./db";

// Your grace period setting (14 days by default). After it, Zahlo cancels the subscription.
const GRACE_DAYS = 14;

/** Access follows the subscription: trialing or active, or past_due while the grace period lasts. */
export function hasAccess(user: User, now = new Date()): boolean {
  if (user.subscription_status === "trialing" || user.subscription_status === "active") return true;
  if (user.subscription_status === "past_due" && user.past_due_since) {
    return now.getTime() - new Date(user.past_due_since).getTime() < GRACE_DAYS * 86_400_000;
  }
  return false;
}

import { cookies } from "next/headers";

import { hasAccess } from "../../lib/access";
import { db, type User } from "../../lib/db";

export const dynamic = "force-dynamic";

// Shows access from the stored subscription. Returning from checkout grants nothing by itself:
// the webhook stores the subscription, usually within seconds.
export default async function AccountPage() {
  const id = (await cookies()).get("uid")?.value;
  const user = id ? (db.prepare("SELECT * FROM users WHERE id = ?").get(id) as User | undefined) : undefined;
  if (!user) {
    return (
      <form action="/api/signin" method="post">
        <input name="email" type="email" required placeholder="you@example.com" />
        <button type="submit">Sign in</button>
      </form>
    );
  }
  if (hasAccess(user)) {
    return (
      <form action="/api/portal" method="post">
        <p>Pro is active ({user.subscription_status}). Welcome, {user.email}.</p>
        <button type="submit">Manage billing</button>
      </form>
    );
  }
  return (
    <form action="/api/subscribe" method="post">
      <p>{user.subscription_id ? `Subscription ${user.subscription_status}.` : "Start your 14-day free trial."}</p>
      <input name="promoCode" placeholder="Promo code" />
      <button type="submit">Subscribe to Pro</button>
    </form>
  );
}

import { createHmac, timingSafeEqual } from "node:crypto";

export type ZahloEvent = {
  id: string;
  type: string;
  livemode: boolean;
  createdAt: string;
  data: { object: { id: string } & Record<string, unknown> };
};

/**
 * Checks `Zahlo-Signature: t=<unix>,v1=<hex>` against the raw request body and returns the parsed event,
 * or null when the signature is missing, wrong or older than 5 minutes. During a secret rotation the
 * header carries one v1 per secret, so any matching v1 is accepted.
 */
export function verifyZahloEvent(
  rawBody: string,
  header: string | null,
  secret: string,
  toleranceSeconds = 300
): ZahloEvent | null {
  const parts = (header ?? "").split(",").map((part) => part.trim().split("="));
  const timestamp = Number(parts.find(([key]) => key === "t")?.[1]);
  const signatures = parts.filter(([key]) => key === "v1").map(([, value]) => value ?? "");
  if (!Number.isInteger(timestamp) || Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) {
    return null;
  }
  const expected = Buffer.from(
    createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex")
  );
  const valid = signatures.some((signature) => {
    const given = Buffer.from(signature);
    return given.length === expected.length && timingSafeEqual(given, expected);
  });
  return valid ? (JSON.parse(rawBody) as ZahloEvent) : null;
}

import { db, transaction } from "../../../../lib/db";
import { type CheckoutSession } from "../../../../lib/subscribe";
import { verifyZahloEvent } from "../../../../lib/webhook-signature";
import { zahlo } from "../../../../lib/zahlo";

type Subscription = {
  id: string;
  status: string;
  pastDueSince: string | null;
  currentPeriodEnd: string | null;
};

const saveSubscription = (subscription: Subscription, userId?: string | null) => {
  const values = [subscription.status, subscription.pastDueSince, subscription.currentPeriodEnd];
  if (userId) {
    // First sight of this subscription: link it to the user who started checkout.
    db.prepare(
      "UPDATE users SET subscription_id = ?, subscription_status = ?, past_due_since = ?, current_period_end = ? WHERE id = ?"
    ).run(subscription.id, ...values, userId);
  } else {
    db.prepare(
      "UPDATE users SET subscription_status = ?, past_due_since = ?, current_period_end = ? WHERE subscription_id = ?"
    ).run(...values, subscription.id);
  }
};

export async function POST(request: Request) {
  // 1. Verify the signature on the raw body before trusting anything in it.
  const rawBody = await request.text();
  const event = verifyZahloEvent(
    rawBody,
    request.headers.get("zahlo-signature"),
    process.env.ZAHLO_WEBHOOK_SECRET ?? ""
  );
  if (!event) return new Response("Invalid signature", { status: 400 });

  // 2. Re-fetch and store the subscription's current state; never apply the event payload, so events
  //    arriving late or out of order cannot grant or revoke access wrongly.
  const id = encodeURIComponent(event.data.object.id);
  let apply: () => void = () => {};
  if (event.type === "checkout.session.completed") {
    const session = await zahlo<CheckoutSession>("GET", `/checkout-sessions/${id}`);
    if (session.type === "subscription" && session.status === "complete" && session.subscriptionId) {
      const subscription = await zahlo<Subscription>("GET", `/subscriptions/${encodeURIComponent(session.subscriptionId)}`);
      apply = () => saveSubscription(subscription, session.reference);
    }
  } else if (event.type.startsWith("subscription.")) {
    const subscription = await zahlo<Subscription>("GET", `/subscriptions/${id}`);
    apply = () => saveSubscription(subscription);
  }

  // 3. Record the event and apply the change in ONE transaction, and answer 2xx only after it commits.
  //    A crash before the commit rolls back both, so Zahlo's retry does the work again.
  transaction(() => {
    const fresh = db
      .prepare("INSERT INTO processed_events (event_id) VALUES (?) ON CONFLICT DO NOTHING")
      .run(event.id);
    if (fresh.changes === 1) apply();
  });
  return new Response("ok");
}

import { userFromRequest } from "../../../lib/auth";
import { zahlo } from "../../../lib/zahlo";

const siteUrl = process.env.SITE_URL ?? "http://localhost:3000";

// "Manage billing": a single-use customer portal link (valid for one hour) for the signed-in user.
// Create a fresh one on every click; never store it.
export async function POST(request: Request) {
  const user = userFromRequest(request);
  if (!user?.subscription_id) return new Response("No subscription", { status: 404 });
  const subscription = await zahlo<{ customerId: string }>(
    "GET",
    `/subscriptions/${encodeURIComponent(user.subscription_id)}`
  );
  const portal = await zahlo<{ url: string }>("POST", "/customer-portal/sessions", {
    body: { customerId: subscription.customerId, returnUrl: `${siteUrl}/account` },
  });
  return Response.redirect(portal.url, 303);
}