Stripe

Leave Localhost supports Stripe as a billing provider via the @convex-dev/stripe component.

Setup

1. Select Stripe as the active provider:

   BILLING_PROVIDER=stripe

   All provider integrations (including the @convex-dev/stripe component) are compiled into the deployment; BILLING_PROVIDER alone decides which one is active. Leaving it blank disables billing regardless of the other variables.

2. Set environment variables in your Convex deployment:

   BILLING_PROVIDER=stripe
   STRIPE_SECRET_KEY=sk_...
   STRIPE_WEBHOOK_SECRET=whsec_...
   STRIPE_PRO_MONTHLY_PRICE_ID=price_...
   STRIPE_PRO_YEARLY_PRICE_ID=price_...
   STRIPE_PRO_LIFETIME_PRICE_ID=price_...

3. Create products and prices in the Stripe dashboard:

   • One product with a monthly recurring price
   • One product with a yearly recurring price
   • One product with a one-time price (for lifetime)

4. Set up the webhook in the Stripe dashboard:

   • URL: https://<your-convex-url>/webhooks/stripe
   • Events: checkout.session.completed, customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, payment_intent.succeeded, charge.refunded

5. Add metadata to checkout sessions: the adapter automatically includes organizationId and planKey in the checkout session metadata so webhooks can resolve the organization.

How It Works

The Stripe adapter at billing/stripe/adapter.ts implements the BillingProviderAdapter interface:

• createCheckout — creates a Stripe Checkout session with the mapped price ID and organization metadata.
• createCustomerPortal — creates a Stripe Customer Portal session for the organization's Stripe customer.
• cancelCurrentSubscription — cancels the active subscription at period end.

Webhook Handler

The Stripe webhook uses @convex-dev/stripe's registerRoutes for signature verification. Event handlers are defined in billing/stripe/webhook.ts.

Local Development

Use the Stripe CLI to forward events:

stripe listen --forward-to https://<your-convex-url>/webhooks/stripe

Copy the webhook signing secret from the CLI output and set it as STRIPE_WEBHOOK_SECRET.

Next Reads

• Webhooks — general webhook architecture.
• Billing Overview — billing system overview.