Next.js boilerplate with Polar

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

File	Job
src/lib/billing/polar.ts	the one lazy Polar client; sandbox unless POLAR_ENVIRONMENT=production
src/lib/billing/provider.ts	billingProvider, the BillingProvider contract from ./types: checkout, portal, webhook verify, translate
src/lib/billing/polar-webhooks.ts	signature check (both Polar secret formats) and body parsing, pure and tested
src/lib/billing/polar-objects.ts	pure mappers: statuses, subscription and purchase rows, receipts, product drift, tested
src/app/api/webhooks/polar/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 Stripe, Dodo and Lemon Squeezy. Its rule is "Billing is one shared layer with one provider adapter". Hold the line between the two:

• The adapter never writes billing state and never sends mail. translate and syncCheckout return BillingEvent[]; applyBillingEvents 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 and the scripts imports @polar-sh/sdk. Not a page, not a component, not entitlements.ts. A feature that needs Polar 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 and exists once. getPolar() builds it on first use and polar is a proxy onto it. A client built at module scope throws during next build on any deployment without keys. Never read POLAR_ACCESS_TOKEN outside polar.ts and missingConfig().

One product is one price

Polar sells one price per product. The catalogue's pro-monthly, pro-yearly and pro-lifetime are three Polar products, and each BILLING_PRICE_* env var holds a product id (a UUID):

pro-monthly   ->  BILLING_PRICE_PRO_MONTHLY=<recurring monthly product id>
pro-lifetime  ->  BILLING_PRICE_PRO_LIFETIME=<one-time product id>

• No product id in code. Sandbox and production have different ids.
• Amounts never come from the client. A buy button is <a href="/billing/checkout?price=pro-monthly">. The route finds the price in src/lib/pricing.ts, the core resolves the product from env, and createCheckout sends only products: [id]. Polar charges the product's own price; bun run billing:sync-plans -- --check and bun run verify fail when it differs from the catalogue.
• The trial is the catalogue's. trialDays on a monthly or yearly price goes to checkout as trialInterval: "day". A price without it sends allowTrial: false, so a trial left on the product in the dashboard never applies by surprise.
• price_id metadata is the second key. billing:sync-plans sets it on every product it creates. The adapter reads a product's plan from the env map first, then that metadata. A subscription never takes its plan from the checkout's metadata: a plan switch in the portal changes the product and leaves the metadata naming the first plan.

The customer is our user id

createCheckout passes externalCustomerId: user.id, so Polar links (or creates) the customer by our id, which is the same in sandbox and production. There is no createCustomer. The portal opens with customerSessions.create({ externalCustomerId }), falling back to the stored customer id. Both return URLs come from returnOrigin(), never a request header.

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

The Polar MCP server

.mcp.json points at Polar's sandbox MCP server (sign in with OAuth from /mcp). Use it to read products, orders and subscriptions while debugging. Do not create or edit products through it: billing:sync-plans does that from src/lib/pricing.ts, the same way in every environment. Its production twin is https://mcp.polar.sh/mcp/polar-mcp; reach for it only when the user asks about live data.

The webhook route is an unauthenticated public endpoint. The signature is the only thing between a Polar 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 Polar parts are verifyWebhook and translate in provider.ts, built on polar-webhooks.ts. Nothing Polar-specific goes in the route.

Read the body as text. processWebhook hands the exact bytes to verifyWebhook. request.json() reorders keys and every signature fails.

Verify with verifyPolarSignature, not the SDK's validateEvent. Polar signs with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature), but the key depends on when the secret was made:

Secret made	HMAC key
before 8 Sep 2026	the UTF-8 bytes of the whole secret
on or after 8 Sep 2026 (whsec_...)	the base64 after whsec_

@polar-sh/sdk 0.49 only knows the first, so it rejects every delivery to a new endpoint. verifyPolarSignature tries both keys (as Polar's 1.0 SDKs do, so the secret polar listen prints works too), compares in constant time and refuses timestamps more than five minutes off. Keep it that way until the SDK you pin does the same. A placeholder secret throws WebhookConfigError (500, Polar keeps retrying); a bad signature throws WebhookSignatureError (400).

Only POLAR_HANDLED_EVENTS do work. Everything else answers 200 ignored and is not even parsed. Adding an event means adding it there, handling it in translate, and subscribing the endpoint to it. The endpoint format must be Raw: Discord and Slack formats sign a chat message, and the parser says so.

The claim is polar:<webhook-id>, before any side effect. The id is stable across Polar's retries of one delivery. A duplicate loses the insert and answers 200 duplicate; a throw releases the claim and answers 500 so Polar retries (up to ten times). Never write billing_processed_events by hand.

Orders are used as delivered; subscriptions are re-read.

• order.paid / order.refunded: the signed payload is the whole order, and an order only moves forward. The purchase upsert keeps status monotonic (pending < failed < paid < partially_refunded < disputed < refunded), so a late paid never undoes a refund. One-time orders (subscriptionId null) become purchase.changed; subscription orders re-read their subscription.
• subscription.*: only the id is taken from the payload. The subscription is fetched with polar.subscriptions.get, because its state goes back and forth and deliveries arrive out of order.

Polar's canceled is not always the end. A customer who cancels keeps access until the period ends; access ends with a revoke, which sets endedAt. normalizeSubscriptionStatus reads canceled with no endedAt and an end still ahead as active with cancelAt set, and /billing shows "Ends on" through scheduledEnd().

Mail is an event. order.paid with an amount above zero returns a payment.receipt, sent inside the claim. There is no dunning event: Polar emails the customer about a failed renewal itself. A mail failure is logged, never rethrown.

Disputes have no webhook. bun run billing:reconcile lists open and lost disputes and marks their purchases disputed. Schedule it.

Status codes are the retry protocol. 400 bad signature, 200 processed, duplicate or ignored, 500 for anything transient. Polar waits 10 seconds and disables an endpoint after 10 failures in a row, so never do slow work inline.