Billing Overview

Leave Localhost includes a complete billing system that supports three payment providers out of the box: Polar, Stripe, and Lemon Squeezy. Billing is optional — the app works without any provider configured.

Architecture

┌─────────────────────────────────────────────────┐
│  Frontend (apps/app)                            │
│  Checkout → Plan selector → Customer portal     │
└──────────────┬──────────────────────────────────┘
               │ Convex actions (createCheckout, createCustomerPortal)
               ▼
┌─────────────────────────────────────────────────┐
│  Billing Layer (packages/backend/convex)         │
│  ┌─────────────┐ ┌──────────────┐ ┌───────────┐ │
│  │ Plan Catalog │ │ Adapter      │ │ Grants    │ │
│  │ (catalog.ts) │ │ (adapter.ts) │ │ (grants.ts│ │
│  └─────────────┘ └──────────────┘ └───────────┘ │
│  ┌─────────────────────────────────────────────┐ │
│  │ Provider Mapping (env vars → plan keys)     │ │
│  └─────────────────────────────────────────────┘ │
└──────────────┬──────────────────────────────────┘
               │ Webhooks (http.ts routes)
               ▼
┌─────────────────────────────────────────────────┐
│  Payment Provider (Polar / Stripe / LemonSqueezy)│
└─────────────────────────────────────────────────┘

Key Concepts

Plan Catalog

The plan catalog at billing/catalog.ts defines every available plan: Free, Pro Monthly, Pro Yearly, and Pro Lifetime. Each plan maps to a set of capabilities.

Provider Adapter

The BillingProviderAdapter interface abstracts checkout, customer portal, and cancellation behind three methods. Each provider implements this interface in its own subdirectory.

Grants

When a webhook event arrives, it is converted into billing grants — rows in the billing_grants table that grant specific capabilities to an organization. The rest of the app checks grants, never provider-specific subscription state.

Provider Selection

Billing is opt-in and ships disabled. Every provider integration is compiled into the deployment, so activating one is a single runtime choice:

1. Set BILLING_PROVIDER to polar, stripe, or lemon_squeezy.
2. Fill that provider's variables and register its webhook URL (see the per-provider guides).

Leaving BILLING_PROVIDER blank keeps billing in "unconfigured" mode: users see the Free plan, and checkout/portal/cancellation fail closed. BILLING_PROVIDER is the sole selector — switching providers is just changing the env var and redeploying; no source is mutated and no install/remove step exists.

Default Plans

Billing Flow

1. User clicks "Upgrade" in the app.
2. Frontend calls createCheckout action with a planKey.
3. The billing adapter creates a checkout session with the provider and returns a redirect URL.
4. User completes payment on the provider's hosted checkout page.
5. Provider sends a webhook event to /webhooks/<provider>.
6. The webhook handler creates/updates grants in the billing_grants table.
7. Capabilities are now active — the app reacts in real time.

Files

Next Reads

• Billing Catalog — customizing plans.
• Free, Pro, and Lifetime Plans — the default plan structure.
• Entitlements and Grants — how grants work.
• Webhooks — webhook event handling.
• Polar, Stripe, Lemon Squeezy — provider-specific setup.
• Removing Billing — removing billing entirely.