react-starter-kit

Billing

Stripe subscriptions are integrated via the @better-auth/stripe plugin. The auth system manages the full subscription lifecycle – customer creation, checkout, webhooks, and status tracking – so billing state lives alongside sessions and organizations in the same database.

Billing is optional – without the STRIPE_* environment variables the app works normally; billing endpoints return 404 and the UI falls back to the free plan.

What’s Included

Feature	Implementation
Three-tier plans (Free / Starter / Pro)	Config in `apps/api/lib/plans.ts`
Stripe hosted checkout	`auth.subscription.upgrade()` client method
Customer portal (cancel, change card)	`auth.subscription.billingPortal()`
Org-level and personal billing	`referenceId` derived from session
Webhook-driven status sync	Plugin-managed endpoint
14-day free trial on Pro	`freeTrial: { days: 14 }` in plan config
Annual discount pricing	`annualDiscountPriceId` on Pro plan

Architecture

┌─────────────┐     POST /api/auth/subscription/upgrade      ┌───────────────┐
│   Browser   │ ──────────────────────────────────────────→  │  API Worker   │
│    (app)    │                                              │    (Hono)     │
│             │  ←── 302 redirect                            │               │
│             │──→ Stripe Checkout (hosted)                  │  Better Auth  │
│             │                                              │  + stripe()   │
│             │    POST /api/auth/stripe/webhook             │  plugin       │
│             │                              Stripe ────────→│  webhook ──→  │
│             │                                              │  update DB    │
│             │    GET  /api/trpc/billing.subscription       │               │
│             │ ──────────────────────────────────────────→  │  tRPC router  │
└─────────────┘  ←── subscription data (TanStack Query)      └───────────────┘

User clicks Upgrade – auth client calls auth.subscription.upgrade()
Plugin creates a Stripe Checkout session – redirects browser to Stripe
User completes payment – Stripe sends webhook to /api/auth/stripe/webhook
Plugin verifies signature, updates subscription table
Client refetches billing state via tRPC + TanStack Query

Mutations (upgrade, portal) go through the auth client because the plugin handles Stripe API calls, session validation, and org authorization internally. Reads go through tRPC to benefit from TanStack Query caching and org-aware cache keys.

Billing Reference

Billing is tied to session.activeOrganizationId when present; otherwise falls back to user.id for personal use. One active subscription per reference ID.

Context	`referenceId`	Who can manage
Organization active	`activeOrganizationId`	Owner or admin
No organization	`user.id`	The user

The server derives referenceId from the session – no client-side parameter needed. The billing query key includes activeOrgId, so switching organizations refetches automatically.

Plans

Three tiers with enforced member limits:

Plan	Members	Trial	Price ID env var
Free	1	–	–
Starter	5	–	`STRIPE_STARTER_PRICE_ID`
Pro	50	14 days	`STRIPE_PRO_PRICE_ID`

See Plans & Pricing for configuration details.

Environment Variables

Variable	Required	Description
`STRIPE_SECRET_KEY`	For billing	Stripe secret key (`sk_test_...` / `sk_live_...`)
`STRIPE_WEBHOOK_SECRET`	For billing	Webhook signing secret (`whsec_...`)
`STRIPE_STARTER_PRICE_ID`	For billing	Stripe price ID for Starter plan (`price_...`)
`STRIPE_PRO_PRICE_ID`	For billing	Stripe price ID for Pro plan (`price_...`)
`STRIPE_PRO_ANNUAL_PRICE_ID`	Optional	Annual discount price for Pro plan (`price_...`)

Set in .env.local for development, Cloudflare secrets for staging/production. See Environment Variables.

File Map

Layer	Files
Schema	`db/schema/subscription.ts`, `stripeCustomerId` on user + organization tables
Server	`apps/api/lib/plans.ts`, `apps/api/lib/stripe.ts`, stripe plugin in `apps/api/lib/auth.ts`
Router	`apps/api/routers/billing.ts`
Client	`stripeClient` in `apps/app/lib/auth.ts`, `apps/app/lib/queries/billing.ts`
UI	Billing card in `apps/app/routes/(app)/settings.tsx`

This site is open source. Improve this page.