Billing

1. 1

   Validate the request boundary

   The checkout route creates a request id, reads the trusted origin, and passes request metadata into the billing checkout service.

   Relevant Product code

   • src/app/api/billing/checkout/route.ts
2. 2

   Resolve runtime policy

   The service reads billing policy, allowed origins, enabled models, provider selection, and setup status before accepting a checkout request.

   Relevant Product code

   • src/features/billing/server/checkout/service.ts
   • src/features/billing/server/runtime/policy.ts
3. 3

   Resolve catalog selection

   The request body is matched to a product, price, billing model, and provider-compatible checkout selection.

   Relevant Product code

   • src/features/billing/server/checkout/request.ts
   • src/features/billing/server/catalog/configuration.ts
4. 4

   Create the provider session

   The active provider adapter creates the checkout session and returns an app response without leaking provider SDK details across the boundary.

   Relevant Product code

   • src/features/billing/server/providers/stripe/checkout.ts
   • src/features/billing/server/providers/lemonsqueezy/checkout.ts

1. 1

   Verify before processing

   The route rate-limits the webhook, validates provider config, reads the raw text body, and verifies the Stripe signature before touching local billing records.

   Relevant Product code

   • src/app/api/webhooks/stripe/billing/route.ts
   • src/lib/security/webhooks/request.ts
2. 2

   Claim the event row

   Existing processed events are returned as duplicates, stale processing leases can be reclaimed, and new events are inserted before dispatch.

   Relevant Product code

   • src/app/api/webhooks/stripe/billing/route.ts
   • src/lib/security/webhooks/processing.ts
3. 3

   Dispatch by event type

   The Stripe handler routes checkout, customer, subscription, invoice, charge, refund, and dispute events to focused handlers.

   Relevant Product code

   • src/features/billing/server/providers/stripe/webhooks/handler.ts
4. 4

   Project locally and notify best-effort

   Billing handlers update local records as the dashboard source of truth, then queue related notifications without blocking billing projection writes.

   Relevant Product code

   • src/features/billing/server/providers/stripe/webhooks/handler.ts
   • src/features/notifications/server/delivery/queue/notify-queue.ts

Use this example as a starting point, then adapt it to your product's rules and configuration.

Environment remains the default source of truth. Settings can override it only when the provider is not locked to env.

export async function getBillingProvider(): Promise<BillingProvider> {
  const envProvider = getBillingProviderFromEnv();
  if (isBillingProviderLockedToEnv()) {
    return envProvider;
  }

  try {
    const { getAppSettings } = await import("@/features/settings/server/queries/settings");
    const settings = await getAppSettings();
    const fromSettings = normalizeProvider(settings.billing?.provider);
    return fromSettings ?? envProvider;
  } catch {
    return envProvider;
  }
}