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.

   • 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.

   • 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.

   • 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.

   • 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.

   • 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.

   • 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.

   • 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.

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

Source: src/features/billing/server/runtime/provider.ts

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;
  }
}