Billing (Stripe)
Stripe integration, subscriptions, and billing flows. This is the pack-billing-stripe pack, the default of the three
billing variants. The other two, Lemon Squeezy and
Polar, are merchants of record and ship the same product shape.
What you need
- A Stripe account. Sign up at dashboard.stripe.com.
- Postgres and Valkey (subscription status is cached in Valkey, keyed by organization).
- Optionally Resend for receipt emails. If
RESEND_API_KEYis set, the pack sends receipts; otherwise it skips email.
Stripe credentials
From the Stripe dashboard, grab:
- Secret key (
STRIPE_SECRET_KEY) and publishable key (STRIPE_PUBLISHABLE_KEY) from API Keys. - Webhook signing secret (
STRIPE_WEBHOOK_SECRET) from Webhooks, or create one locally with the Stripe CLI (below). - Price IDs for the plans you sell (
STRIPE_PRICE_PRO,STRIPE_PRICE_PREMIERin the pack's env schema).
Data model
There is no Prisma "subscriptions" table in this pack. Billing state is org-scoped and stored in Valkey:
| Key pattern | Meaning |
|---|---|
stripe:org:{organizationId} | Stripe customer id for that organization |
stripe:customer:{customerId} | Cached subscription / billing status |
Checkout, portal, and webhook sync code live under apps/backend/src/features/billing/ and
apps/backend/src/libs/stripe/. Organization admins get MANAGE:BILLING through the pack's permission grants.
Checkout and portal flow
Subscribe an organization
Create checkout
The frontend calls the billing module. The backend creates a Stripe Checkout session for the org's customer (creating one if needed).
Customer pays in Stripe
Stripe hosts the checkout UI. Success returns to the pack's checkout-success route.
Webhook sync
POST /checkout/webhook verifies the signature, then syncs customer and subscription status into Valkey.
Customer portal
create-billing-portal opens Stripe's portal for plan changes and invoices against the same org customer.
Webhook endpoint
The pack exposes a Stripe webhook receiver at:
POST /checkout/webhookIn production, create a webhook endpoint in Stripe pointing at https://your-api-origin/checkout/webhook, subscribe to
the events the pack handles (checkout, subscription, customer), and copy the signing secret into
STRIPE_WEBHOOK_SECRET.
Local development with the Stripe CLI
Stripe cannot reach localhost over the internet, so use the Stripe CLI to forward events. Install it from
stripe.com/docs/stripe-cli, then:
stripe listen --forward-to localhost:3000/checkout/webhookThe CLI prints a whsec_... signing secret. Put it in STRIPE_WEBHOOK_SECRET.
Failure and retry notes
- Signature verification failures reject the webhook. Fix the secret before debugging business logic.
- Sync helpers update the Valkey cache from Stripe's customer / subscription objects. If the UI looks stale after a portal change, confirm the webhook events are arriving and the org → customer mapping exists.
- Receipt email is best-effort: without
RESEND_API_KEYthe send path returns early and checkout still succeeds.
Environment variables
| Variable | Purpose |
|---|---|
STRIPE_SECRET_KEY | Stripe API secret key |
STRIPE_PUBLISHABLE_KEY | Publishable key the frontend uses |
STRIPE_WEBHOOK_SECRET | Signing secret for the webhook endpoint |
STRIPE_PRICE_PRO | Stripe Price ID for Pro |
STRIPE_PRICE_PREMIER | Stripe Price ID for Premier |
RESEND_API_KEY | Optional. Enables receipt emails |
One subscription per customer
In the Stripe dashboard, under Settings > Checkout and Payment Links, turn on Limit customers to one subscription. The pack keys billing state by organization, and that setting is what stops a second checkout from creating a parallel subscription. The CLI prints this reminder after install.
Gate a feature by plan
The plan belongs to the organization, not to the person: every member of a paying org gets the paid features. There are
three plans, free, pro, and premier, in features/billing/constants/plans.ts. This section is the same for all
three billing packs, so code written against it keeps working if you switch providers.
On the backend
import { getPlanRank } from "@backend/features/billing/constants/plans";
import { getSubscriptionStatus } from "@backend/features/billing/modules/get-subscription-status";
import { ApplicationError, ApplicationErrorCode } from "@backend/middleware/error";
const { plan } = await getSubscriptionStatus({ organizationId });
if (getPlanRank(plan) < getPlanRank("pro")) {
throw new ApplicationError({
code: ApplicationErrorCode.FORBIDDEN,
message: m.invoices_error_needs_pro(),
statusCode: 402,
});
}What plan tells you:
- It is
proorpremieronly while the subscription isactiveortrialing. Apast_due,unpaid, orcanceledsubscription reads asfree. - A subscription cancelled at period end keeps its plan until the period ends, with
cancelAtPeriodEnd: true. - The call reads Valkey, never Stripe, so it is cheap enough for every request. Webhooks keep the cache current. With no
cached entry, for example when the webhook was never set up, every organization reads as
free.
For limits that differ per plan (seats, exports per month, storage), keep one table keyed by plan and look it up:
import type { PlanKey } from "@backend/features/billing/constants/plans";
const INVOICE_LIMITS = {
free: { monthly: 10 },
pro: { monthly: 500 },
premier: { monthly: null },
} satisfies Record<PlanKey, { monthly: number | null }>;
const { monthly } = INVOICE_LIMITS[(await getSubscriptionStatus({ organizationId })).plan];The AI chat pack does exactly this for its token and image allowances.
In the UI
GET /checkout/status returns the plan, but every /checkout route needs manage:billing, which only admins have.
Members get a 403 from it. To show or hide a feature for everyone, return the plan from your own feature's route, which
already runs as the member:
.get("/access", hasAccess({ action: "read", subject: "invoice" }), async (ctx) => {
const { plan } = await getSubscriptionStatus({ organizationId: ctx.var.organizationId });
return ctx.json({ plan });
})Hide or disable the feature from that response, and keep the backend check. The UI check is only there so people see an upgrade prompt instead of an error.
There is no ready-made withPlan middleware or usePlan hook yet. The snippets above are the whole pattern.
In the admin
On top of a starter, this pack adds a revenue row to the admin app dashboard, a
billing card and a revenue card on the organization details page, and /admin/billing API routes. Nothing extra to
configure beyond Stripe env vars; the UI shows up once both packs are installed.
Surfaces
Web, admin, and mobile. The Expo app gets the billing screen and the checkout handoff to Stripe's hosted page.
Related
- Organizations for the tenant boundary billing attaches to
- Mailing for receipt templates
- Going to production for webhook URL checklist