Billing & subscriptions

Valcraven ships a complete Stripe billing integration: hosted checkout for recurring subscriptions and one-time "lifetime" purchases, the Stripe customer portal for self-service management, and a webhook handler that keeps every user's plan and subscriptionStatus in sync with Stripe. The Stripe client lives in lib/stripe.ts; the routes live under app/api/stripe/.

You don't build the billing plumbing — you configure a few env vars and Stripe prices, then read the user's plan where your feature needs to gate access.

How it fits together

• lib/stripe.ts exposes a single lazy-initialized client via getStripe(). It reads STRIPE_SECRET_KEY on first use, so importing the module never crashes when Stripe isn't configured.
• Four API routes under app/api/stripe/ handle checkout, the portal, status reads, and the webhook.
• The user table carries the billing state as custom columns: plan (default "free"), stripeCustomerId, stripeSubscriptionId, and subscriptionStatus (default "inactive"). See Data layer.
• A cron job (sync-stripe-status) reconciles subscription status hourly as a backstop to the webhook.

The Stripe client

import { getStripe } from "@/lib/stripe";

const stripe = getStripe();

getStripe() returns a memoized Stripe instance configured with the SDK's pinned API version. It's server-only — never import it into a client component.

Checkout

POST /api/stripe/create-checkout creates a Stripe Checkout Session and returns its hosted URL. The route:

1. Requires an authenticated session (401 otherwise).
2. Blocks the action while an admin is impersonating a user (403).
3. Looks up the user's stripeCustomerId, creating a Stripe customer (with metadata.userId) and persisting the id if one doesn't exist yet.
4. Creates the checkout session and returns { url }.

The request body selects the checkout type:

Both sessions enable promotion codes, use ${APP_URL}/app?upgraded=1 as the success URL, and ${APP_URL}/app as the cancel URL. If the relevant price env var is unset, the route returns a 500 ("Checkout not configured").

Triggering checkout from the frontend

const res = await fetch("/api/stripe/create-checkout", { method: "POST" });
const { url } = await res.json();
window.location.href = url; // redirect to Stripe hosted checkout

For the lifetime deal, send a JSON body:

const res = await fetch("/api/stripe/create-checkout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ type: "lifetime" }),
});

Customer portal

GET /api/stripe/portal returns { url } for a Stripe billing portal session, where users can update payment methods, view invoices, and cancel. The route requires an authenticated session, blocks impersonation, and returns 404 if the user has no stripeCustomerId yet (i.e. they've never checked out). The portal returns the user to ${APP_URL}/app.

const res = await fetch("/api/stripe/portal");
const { url } = await res.json();
window.location.href = url;

Reading the user's plan

There are two ways to know a user's plan, depending on where you are.

In an API route or server code, read it straight off the session:

const session = await auth.api.getSession({ headers: request.headers });
if (session?.user.plan !== "pro") {
  return new Response("Upgrade required", { status: 403 });
}

From the client, call the status endpoint:

const res = await fetch("/api/stripe/status");
const { plan, status } = await res.json();

GET /api/stripe/status returns { plan, status }. Note that plan comes from getEffectivePlan() in lib/admin.ts, so it reflects any admin-granted plan override in addition to the user's paid plan — see Admin. status is the raw subscriptionStatus column (defaults to "inactive").

Webhook: keeping plans in sync

POST /api/stripe/webhook is the source of truth for plan changes. It verifies the Stripe signature using STRIPE_WEBHOOK_SECRET (rejecting unsigned or tampered requests with a 400) and handles these events:

Each handler matches the user by stripeCustomerId, fires the matching transactional email (subscription confirmation, lifetime purchase, cancellation, or payment-failed — see Email), records an audit log entry, and updates marketing status. Unhandled event types are ignored.

The webhook must receive the raw request body to verify the signature — the route reads request.text() before parsing. Don't put body-parsing middleware in front of it.

Registering the webhook

Point a Stripe webhook endpoint at https://<your-domain>/api/stripe/webhook and copy its signing secret into STRIPE_WEBHOOK_SECRET. In local dev, use the Stripe CLI to forward events:

stripe listen --forward-to localhost:3000/api/stripe/webhook

The sync-stripe-status cron

Webhooks are the primary sync mechanism, but Valcraven also runs a scheduled backstop. sync-stripe-status runs hourly (0 * * * * in wrangler.toml's [triggers]), iterates every user with a stripeCustomerId, fetches their latest subscription from Stripe, and writes subscriptionStatus. If STRIPE_SECRET_KEY isn't set, the job logs and skips — it never throws.

The job is registered in jobs/index.ts and mapped to its cron expression in lib/scheduled.ts. On Cloudflare Workers, cron triggers fire the scheduled() handler (in worker.js), which requires the CRON_SECRET secret to run. See Cloudflare Workers.

Environment variables

See Secrets & env for setting these on Cloudflare, and Environment variables for the full list.

Extending billing

• More plans/tiers. Add prices in Stripe, branch on type (or a priceId) in create-checkout, and map the resulting plan value in the webhook's checkout.session.completed handler.
• Gate features by plan. Read session.user.plan server-side, or call getEffectivePlan() when you want admin overrides to count. Never trust a client-supplied plan.
• Admin overrides. Admins can grant a plan without a Stripe charge via plan overrides; getEffectivePlan() already merges these in, which is why /api/stripe/status reports the effective plan.

Gotchas

• Impersonation blocks billing. Both checkout and the portal return 403 while an admin is impersonating, so you can't accidentally start a charge on someone else's account.
• Lifetime users are protected on cancellation. The customer.subscription.deleted handler explicitly skips lifetime users so a stray subscription-cancel event can't strip their access.
• plan vs. subscriptionStatus. plan is the entitlement (free / pro / lifetime); subscriptionStatus mirrors Stripe (active, past_due, inactive, …). Gate features on plan; surface subscriptionStatus for billing UI.