Next.js boilerplate with Stripe

Billing here is one shared layer plus one adapter. This battery ships only the adapter:

File	Job
src/lib/billing/stripe.ts	the one lazy Stripe client, API version pinned
src/lib/billing/provider.ts	billingProvider, the BillingProvider contract from ./types: checkout, portal, webhook verify, translate
src/lib/billing/stripe-objects.ts	pure reads of Stripe objects (status, periods, invoice parent, purchase status), tested
src/app/api/webhooks/stripe/route.ts	three lines into the shared processWebhook
scripts/billing/*.ts	sync-plans, reconcile, prune-events

Everything else under src/lib/billing, plus /pricing, /billing and src/components/billing, is the stack's shared code and works the same for Polar, Dodo and Lemon Squeezy. Hold the line between the two:

• The adapter never writes billing state and never sends mail. translate and syncCheckout return BillingEvent[] (customer.linked, subscription.changed, purchase.changed, payment.receipt, payment.failed). applyBillingEvents in webhook.ts is the only writer and runs them inside the idempotency claim. The one store call the adapter makes is a read: getUserIdForCustomer.
• Nothing outside the adapter imports stripe. Not a page, not a component, not entitlements.ts. A feature that needs Stripe data gets a method on BillingProvider (all four providers implement it) or a field on a BillingEvent. Never a branch on billingProvider.id in shared code.
• Re-read, then translate. Every handler retrieves the subscription, invoice or Checkout Session by id through the pinned client before mapping it. Payloads arrive out of order and in the API version of whatever endpoint sent them.
• Version-sensitive fields live in stripe-objects.ts. The renewal date on subscription items, the subscription id under invoice.parent, cancel_at versus cancel_at_period_end, a charge's refund and dispute flags. That file has no import "server-only", so its tests load it. When a Stripe upgrade moves a field, change it there and add a fixture.
• Statuses are normalized, and Stripe's word is kept. normalizeSubscriptionStatus maps Stripe's status onto the shared SubscriptionStatus (incomplete_expired becomes expired, an unknown word grants nothing). The row stores both, status and providerStatus.
• One-time and subscription share one checkout. createCheckout picks mode: "payment" for a one_time catalogue price and mode: "subscription" otherwise, and puts { userId, planSlug, priceId } on the session and on what it creates (the PaymentIntent and invoice, or the subscription).

Scripts may import the store, @/lib/billing/webhook and the adapter because they run with bun --conditions=react-server. verify runs with bun and may import only the pure files (catalog, price-refs, format, types) and the SDK.

The contract itself (types, entitlement rules, the store and its tables) is in the shared layer. Its rule is "Billing is one shared layer with one provider adapter".

The catalogue is code: src/lib/pricing.ts. Plans, features, and a monthly, yearly or one-time price for each, in minor units. /pricing, /billing and checkout all read it. Stripe holds the matching prices, and each catalogue price is tied to one by an env var named after its id:

pro-monthly   ->  BILLING_PRICE_PRO_MONTHLY=price_...
pro-lifetime  ->  BILLING_PRICE_PRO_LIFETIME=price_...   (a one-off price)

src/lib/billing/price-refs.ts reads those with literal process.env reads and satisfies Record<PriceId, ...>, so a price with no env line is a type error.

Hold to these:

• No price_... string in code. Not in a component, not in pricing.ts, not in a script. Test and live mode have different ids, and the env var is what lets one build serve both.
• Never trust an amount, currency, interval, quantity or trial from the client. A buy button is <a href="/billing/checkout?price=pro-monthly">. The route looks the id up in the catalogue, startCheckout resolves the Stripe price from env, and the session is built from those. Anything else in the request is ignored.
• An unknown id is refused, not passed through. findPrice returns null and the route redirects to /pricing?error=unknown-price. isValidPriceRef rejects an env value that is not a price_... id before Stripe sees it.
• The catalogue amount is for display. Stripe charges its own. Keep them equal with bun run billing:sync-plans -- --check, which exits 1 on any drift in amount, currency or interval. bun run verify runs the same check on every set BILLING_PRICE_*.
• Stripe prices are immutable once used. A new amount is a new Stripe price and usually a new catalogue id (pro-monthly-v2). Never rename a catalogue id somebody has paid for: it is stored on their subscription and purchase rows.
• Money is integers in minor units. 1900 is $19.00. Render only through formatPrice / formatAmount in src/lib/billing/format.ts, which reads the currency's own exponent (JPY has none, KWD has three).

To add a plan or a price: edit src/lib/pricing.ts, add its line to price-refs.ts, run bun run billing:sync-plans (it creates the product plan_<slug> and the price, with the catalogue id as its lookup key) and paste the printed env line. The /add-plan skill walks through it.

The Stripe SDK is constructed exactly once, in src/lib/billing/stripe.ts, which starts with import "server-only". Nothing else calls new Stripe(...) (the verify check builds its own because it runs outside Next.js).

It is built lazily, by getStripe(). next build imports every module a page can reach, so a client built at module scope throws during the build of any deployment with no payment secrets yet: a preview, a fresh clone. The exported stripe is a proxy onto the same memoised client, so stripe.checkout.sessions.create(...) reads like every Stripe example while importing the module costs nothing. Do not "simplify" it into const stripe = new Stripe(...).

Never import stripe, provider.ts or @/lib/billing into a "use client" file or a module a client component imports. server-only turns that into a build error rather than a leaked STRIPE_SECRET_KEY, but the error is the backstop, not the design. Client components may import the pure files (catalog, format, types, entitlement).

Never read process.env.STRIPE_SECRET_KEY outside stripe.ts and the adapter's missingConfig() (which only checks it is set and not a placeholder, so billing can say "not set up" instead of throwing).

Never build a return URL from a request header. Success, cancel and portal return URLs come from returnOrigin() in src/lib/billing/origin.ts, which checks the host against NEXT_PUBLIC_APP_URL and the platform's own deployment URLs. x-forwarded-host is client-settable.

Checkout and the portal are hosted pages. The flow is:

1. A buy button is a plain <a href="/billing/checkout?price=pro-monthly"> (never next/link: a prefetch would create a checkout session).
2. GET /billing/checkout reads the session. Signed out, it counts the visitor's address and sends them to sign-up with the checkout as the way back. Signed in, it calls startCheckout({ user, priceId }).
3. startCheckout checks the price and impersonation, counts the attempt against the rate limit (per user and per address, in Postgres), checks that the user does not already own it, config and email, then calls the adapter's createCustomer (once per user) and createCheckout. Over the limit, Stripe is never called.
4. The route answers 303 to session.url. Any BillingError becomes a 303 to /billing?error=<code>, which renders a sentence. Never a 500.

The portal is the openBillingPortal server action. A server action is a public POST endpoint, so it reads the user from the session with requireUser() and derives the Stripe customer from the stored mapping. Never take a user id, email or customer id from form data.

Billing never imports an auth SDK. src/lib/billing/user.ts turns the SessionUser from @/lib/auth/session into a BillingUser, and that is the only place the two meet. While an admin impersonates a user (impersonatedBy is set), checkout and the portal refuse with BillingError("impersonating"): both act on the customer's card.

BillingUser.email can be null. Do not paper over it with ?? "". requireBillingEmail() throws no-email before a Stripe customer is created, because a customer with no address never gets a receipt, an invoice or a failed-payment warning.

Do not add a route that proxies arbitrary Stripe calls (/api/stripe/[...path]). It is a credential-forwarding endpoint with extra steps.

The webhook route is an unauthenticated public endpoint. The signature is the only thing between a Stripe event and a forged POST that grants a lifetime plan.

The route is three lines: processWebhook(billingProvider, request). The pipeline in src/lib/billing/webhook.ts is shared by every provider, and the Stripe parts are verifyWebhook and translate in provider.ts. Keep it that way: nothing Stripe-specific in the route.

Read the body as text. processWebhook calls request.text() and hands those exact bytes to verifyWebhook. request.json() reorders keys and every signature check fails. Never add a body parser or middleware in front of it.

Always verify with constructEventAsync, the raw body, the stripe-signature header and STRIPE_WEBHOOK_SECRET. A missing or placeholder secret throws WebhookConfigError (500, Stripe keeps retrying until you set it). A bad signature throws WebhookSignatureError (400, a retry would fail the same way). There is no "skip it locally": bun run stripe:listen gives you a real secret.

Only the events in HANDLED_EVENTS do work. Everything else answers 200 ignored and writes nothing. Adding an event means adding it there, handling it in translate, and subscribing the dashboard endpoint to it.

The claim comes before any side effect. processWebhook inserts stripe:<event id> into billing_processed_events first. A duplicate loses the insert and answers 200 duplicate. On a throw the claim is released and the answer is 500, so Stripe's retry runs the work again. On success it is stamped complete. Do not reorder those, and do not write that table by hand.

Receipts and dunning mail are events, not calls. translate returns payment.receipt (from invoice.paid, amount above zero) and payment.failed (from invoice.payment_failed). applyBillingEvents sends them inside the claim and logs a failure instead of throwing: the payment is already recorded, and a 500 now would redeliver it and mail the customer twice.

Re-read, never trust the payload. Every case in translate retrieves the object by id first (subscription, invoice, Checkout Session with line_items and payment_intent.latest_charge expanded). Events arrive out of order, and a payload is shaped by the API version of the endpoint that sent it, which can be older than the pinned one.

One-time payments are decided by the session, not the event name. checkout.session.completed in mode: "payment" is only paid when payment_status is paid (or no_payment_required for a 100% coupon). Bank debits complete days earlier with unpaid, then send checkout.session.async_payment_succeeded or _failed. Refunds (charge.refunded) and disputes (charge.dispute.created) find the session through the PaymentIntent and rewrite the same purchase row, which revokes the plan.

Status codes are the retry protocol. 400 bad signature, 200 processed, duplicate or ignored, 500 for anything transient. Never swallow an error into a 200: that drops a paid subscription on the floor.

Return fast. Stripe gives up at about 20 seconds. maxDuration = 60 is headroom, not budget.

The ledger is not a log. bun run billing:prune-events deletes completed rows older than 30 days and reports claims that never completed. Do not delete a stuck claim to "clean up": it hands the next redelivery a clean slate to re-run its side effects on.