Next.js boilerplate with Lemon Squeezy

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

File	Job
src/lib/billing/lemonsqueezy.ts	lazy SDK setup, unwrap(), the mode and the store id
src/lib/billing/provider.ts	billingProvider, the BillingProvider contract from ./types: checkout, portal, webhook verify, translate
src/lib/billing/lemonsqueezy-objects.ts	pure reads of Lemon Squeezy objects (payload schemas, statuses, orders, invoices, variant drift), tested
src/lib/billing/lemonsqueezy-signature.ts	the X-Signature HMAC check
src/lib/billing/lemonsqueezy-fixtures.ts	real webhook bodies for tests and billing:test-webhook. Never imported by the app
src/app/api/webhooks/lemonsqueezy/route.ts	three lines into the shared processWebhook
scripts/billing/*.ts	sync-plans, reconcile, prune-events, test-webhook

Everything else under src/lib/billing, plus /pricing, /billing and src/components/billing, is shared code that works the same for Stripe, Polar and Dodo. Hold the line between the two:

• The adapter never writes billing state and never sends mail. translate returns BillingEvent[]; applyBillingEvents in webhook.ts is the only writer. The adapter's store calls are reads: getUserIdForCustomer and findPurchaseByPaymentId.
• Nothing outside the adapter imports @lemonsqueezy/lemonsqueezy.js. A feature that needs Lemon Squeezy data gets a method on BillingProvider or a field on a BillingEvent. Never a branch on billingProvider.id in shared code.
• Set the SDK up lazily. ensureLemonSqueezy() runs lemonSqueezySetup on first use. next build imports modules with no secrets set, so a module-scope setup breaks every preview build.
• The SDK never throws on an HTTP error. It returns { data, error }. Every call goes through unwrap(), or checks error and statusCode itself (a 404 on a re-read is a fallback case, not an outage).

Plans live in pricing.ts, variant ids live in env

The catalogue is src/lib/pricing.ts. Each price is sold as one Lemon Squeezy variant, named by an env var: pro-monthly is BILLING_PRICE_PRO_MONTHLY, read literally in price-refs.ts. isValidPriceRef accepts digits only.

• No variant, product or store id in code. Test and live mode have different ids.
• The catalogue decides one-time versus subscription. A one_time price must point at a single-payment variant, month and year at subscription variants. billing:sync-plans and verify check the kind, amount, currency, interval, trial, store and mode of every set id with variantDrift.
• Lemon Squeezy's API cannot create products. The dashboard is where they are made; billing:sync-plans finds matching variants and prints the env lines. Never "fix" drift by editing the check.

Checkout sells one variant, priced on the server

createCheckout is called by the shared startCheckout with a catalogue price that was already validated.

• productOptions.enabledVariants is always [variantId]. Without it the hosted page lets the buyer switch to any variant of the product.
• Never pass customPrice from anything a user sent. It overrides the price of every renewal, not only the first charge.
• checkoutData.custom carries { userId, planSlug, priceId }. Lemon Squeezy echoes it as meta.custom_data on every order and subscription webhook. It names the user; it never names the plan (a buy link can carry any custom data, the variant that was paid for cannot be faked).
• Trials are a variant setting. A recurring price without trialDays sends skipTrial: true, so the catalogue stays the promise.
• testMode comes from LEMONSQUEEZY_MODE (default test) on every checkout, and verify fails when the API key's own mode disagrees.

The portal URL is a credential

urls.customer_portal is pre-signed and valid for 24 hours. createPortal fetches it fresh from the subscription (or the customer) on every click. Never store it, log it or put it in an email. A buyer with no subscription has no portal: Lemon Squeezy returns null and so does createPortal.

Scripts

Scripts that read the store or the adapter run with bun --conditions=react-server. verify and billing:test-webhook run with bun and import only pure files (catalog, price-refs, format, types, lemonsqueezy-objects, lemonsqueezy-signature, lemonsqueezy-fixtures) and the SDK. Importing lemonsqueezy.ts or provider.ts there throws on server-only.

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 webhook route is a public URL with no session. The signature is the only thing between a Lemon Squeezy 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 Lemon Squeezy parts are verifyWebhook and translate in provider.ts. Keep it that way: nothing Lemon Squeezy specific in the route.

Verify first, on the raw body

• processWebhook reads await request.text() and hands those exact bytes to verifyWebhook. Never parse, re-stringify or add a body parser in front.
• isValidSignature in lemonsqueezy-signature.ts compares the hex HMAC-SHA256 in constant time. Use it; do not write a second one.
• A missing or placeholder LEMONSQUEEZY_WEBHOOK_SECRET throws WebhookConfigError (500, Lemon Squeezy retries). A missing or wrong X-Signature throws WebhookSignatureError (400). The body is parsed only after the signature matched.
• No "local dev" bypass. bun run billing:test-webhook signs fixtures with your real secret.

The idempotency key is built, not received

Lemon Squeezy sends no delivery id, and meta.webhook_id names the webhook configuration, not the delivery. webhookEventKey builds one from what a retry keeps and a real change moves:

<event_name>:<data.type>:<data.id>:<data.attributes.updated_at>

The shared pipeline claims lemonsqueezy:<key> before any side effect. A duplicate answers 200 duplicate; a throw releases the claim and answers 500. Never drop the event name from the key (subscription_updated and subscription_cancelled share one updated_at) and never change its shape without a plan for in-flight retries.

What translate may trust

• Orders come from the signed payload. An order only moves forward (paid, then refunded), and the shared purchase upsert never moves a row backwards, so the order deliveries land in cannot matter.
• Subscriptions and invoices are re-read with getSubscription and getSubscriptionInvoice. They move both ways, and subscription_updated fires beside almost every other event. The payload is only a fallback when the API answers 404.
• A purchase is a one-time price by the catalogue, never by the payload. order_created fires for every order, including a subscription's first payment. Only an order whose variant maps to a one_time catalogue price (or that already has a purchase row) becomes a purchase.
• Custom data names the user, not the plan. The plan comes from the variant. A subscription's plan comes from its current variant only.
• Drop other-mode and other-store events. translate returns no events when meta.test_mode disagrees with LEMONSQUEEZY_MODE or store_id is not LEMONSQUEEZY_STORE_ID. A 4242 test purchase must never entitle anyone on production.

Never answer 200 for money you did not record

A paid one-time order that no local user can be matched to throws UnmatchedOrderError: 500, red in the dashboard, retried. A quiet 200 would mark it done and make that money unrecordable through the webhook. Money fields are validated with zod (Number.isInteger, no ?? 0, no ?? "usd").

Mail is an event

translate returns payment.receipt (paid one-time orders, paid subscription invoices) and payment.failed (declined renewals whose invoice is still unpaid). The core sends them inside the claim and logs a failure instead of throwing. Never send mail from the adapter.

The handled events are a list you keep in sync

HANDLED_EVENTS in provider.ts is the source of truth. The events ticked on the webhook in the dashboard must match it, for both the test-mode and live-mode webhooks. Anything else answers 200 ignored and writes nothing.

Three retries is a short fuse

Lemon Squeezy retries a failed delivery three more times (about 5s, 25s, 125s) and then stops. bun run billing:reconcile rebuilds subscriptions and recent orders from the API; schedule it nightly. billing:prune-events trims completed claims and reports stuck ones. Never delete a stuck claim to "clean up".