Next.js boilerplate with Dodo Payments

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

File	Job
src/lib/billing/dodo.ts	the one lazy Dodo client (getDodo(), dodo)
src/lib/billing/dodo-config.ts	env reads: key, webhook key, DODO_PAYMENTS_ENVIRONMENT, placeholder check. Pure
src/lib/billing/provider.ts	billingProvider, the BillingProvider contract: customer, checkout, portal, verify, translate
src/lib/billing/dodo-events.ts	HANDLED_EVENTS, signature check, event translation, success-page sync. Pure, I/O injected
src/lib/billing/dodo-objects.ts	payment, subscription and product reads (status, refunds, trial). Pure, tested
src/lib/billing/dodo-fixtures.ts	recorded payloads for the tests and dodo:test-webhook
src/app/api/webhooks/dodo/route.ts	three lines into the shared processWebhook
scripts/billing/*.ts	sync-plans, reconcile, prune-events, dodo-test-webhook

Everything else under src/lib/billing, plus /pricing, /billing and src/components/billing, is the stack's shared code. Its rule is "Billing is one shared layer with one provider adapter". Hold the line:

• The adapter never writes billing state and never sends mail. translate and syncCheckout return BillingEvent[]. 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 dodopayments. Not a page, not a component, not entitlements.ts. A feature that needs Dodo data gets a method on BillingProvider or a field on a BillingEvent. Never a branch on billingProvider.id in shared code.
• The client is built lazily, once. next build imports every module a page can reach, so new DodoPayments(...) at module scope throws on any deploy with no keys yet. Do not "simplify" getDodo() away. Only dodo-config.ts reads DODO_PAYMENTS_API_KEY.
• Nothing Dodo reaches the browser. Checkout and the portal are hosted. Never import dodo.ts, provider.ts or @/lib/billing into a "use client" file. server-only makes that a build error.

Products, prices and one-time

The catalogue is src/lib/pricing.ts. Dodo holds one price per product, so each catalogue price is its own Dodo product, tied by an env var named after the price id:

pro-monthly   ->  BILLING_PRICE_PRO_MONTHLY=pdt_...   (subscription product)
pro-lifetime  ->  BILLING_PRICE_PRO_LIFETIME=pdt_...  (single payment product)

• No pdt_... in code. Test and live mode have different ids.
• Never trust an amount, interval or trial from the client. The buy button sends a catalogue id; the product comes from env; the trial comes from the catalogue (subscription_data.trial_period_days, 0 overrides a trial set on the product).
• One-time or subscription is Dodo's product type. createCheckout sends the same session either way. A payment is one-time when it charges no subscription: subscription_ids empty, not subscription_id null alone (a multi-subscription payment leaves that null).
• The plan comes from the product, never the metadata. For a subscription, a portal plan change swaps the product and leaves the checkout metadata naming the old plan. For a one-time payment, a static payment link copies any metadata_* query parameter the buyer types into the metadata. An unmapped product stores planSlug null, which unlocks nothing.
• Statuses are normalized, and Dodo's word is kept. on_hold is unpaid (no access: Dodo stopped charging and waits for a new card). past_due is Dodo's grace period and keeps access. An active subscription inside trial_period_days is trialing.

billing:sync-plans creates missing products (metadata price_id is the catalogue id) and exits 1 on drift. verify runs with bun, outside Next.js: it may import only the pure files (catalog, price-refs, format, dodo-config, dodo-objects) and the SDK, never dodo.ts, provider.ts or the store.

Customers

createCustomer makes one Dodo customer per user before the first checkout, with metadata.userId, and the core stores it with linkCustomer, which never overwrites. Test-mode and live-mode customers are different objects: point one database at one mode, or clear billing_customers when you switch.

The webhook route is an unauthenticated public endpoint. The signature is the only thing between a Dodo 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. The Dodo parts are verifyDodoWebhook and translateDodoEvent in dodo-events.ts. Keep it that way: nothing Dodo-specific in the route.

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

Verify the Standard Webhooks way, with the library. new Webhook(key) .verify(rawBody, headers) from standardwebhooks, with all three headers: webhook-id, webhook-timestamp, webhook-signature. The timestamp is inside the signed string and must be within five minutes, which is what stops a captured delivery being replayed. Never hand-roll the HMAC. A missing or placeholder DODO_PAYMENTS_WEBHOOK_KEY throws WebhookConfigError (500, Dodo retries until you set it). A bad signature, a missing header or a stale timestamp throws WebhookSignatureError (400).

Only HANDLED_EVENTS do work. Everything else answers 200 ignored and writes nothing. Adding an event means adding it to the array, handling it in translateDodoEvent, adding a fixture test, and subscribing both Dodo endpoints (test and live) to it.

The claim comes before any side effect. processWebhook inserts dodo:<webhook-id> into billing_processed_events first. A duplicate answers 200 duplicate. On a throw the claim is released and the answer is 500, so Dodo's retry runs the work again. Never key on a payment id or a timestamp: webhook-id is the value Dodo keeps stable across retries.

Re-read what can be stale, trust what is signed and monotonic.

• subscription.* and renewal payments re-read the subscription with dodo.subscriptions.retrieve. Dodo retries for a day, so an old subscription.active can land after the subscription.cancelled that replaced it.
• refund.succeeded, dispute.opened and dispute.lost re-read the payment: the refund or dispute payload does not say what was bought, and the payment carries every refund and dispute so far.
• A one-time payment.succeeded or payment.failed is written from the signed payload. The purchase upsert only moves status forward, so a stale "paid" can never undo a refund, and the path needs no network.

One-time is decided by the payment, not the event name. payment.succeeded fires for renewals too. Only a payment whose subscription_ids is empty (and that is not a card-change charge, is_update_payment_method) is a purchase. Treating a renewal as a purchase would hand out a lifetime plan for a monthly charge.

Receipts and warnings are events, not calls. translate returns payment.receipt (paid, above zero) and payment.failed (a declined renewal whose subscription is now past_due or unpaid). applyBillingEvents sends them inside the claim and logs a failure instead of throwing.

A payment with no local user is skipped loudly, not guessed. The user comes from metadata.userId (our checkout writes it), then from billing_customers. With neither, translate reports it and returns no events. Fix the mapping, then resend the event from the Dodo dashboard, or run bun run billing:reconcile.

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 payment on the floor.

Test with signed deliveries only. bun run dodo:listen forwards real test events, and bun run dodo:test-webhook signs a fixture with your own key. Never add an "unsafe unwrap" path for Dodo CLI mock events, which are unsigned.