Polar

Leave Localhost supports Polar as a billing provider.

Setup

1. Select Polar as the active provider:

   BILLING_PROVIDER=polar

   All provider integrations 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=polar
   POLAR_ORGANIZATION_TOKEN=org_...
   POLAR_SERVER=sandbox          # or "production"
   POLAR_WEBHOOK_SECRET=...
   POLAR_PRO_MONTHLY_PRODUCT_ID=...
   POLAR_PRO_YEARLY_PRODUCT_ID=...
   POLAR_PRO_LIFETIME_PRODUCT_ID=...

3. Create products in the Polar dashboard:

   • A monthly subscription product
   • A yearly subscription product
   • A lifetime (one-time) product

4. Set up the webhook in the Polar dashboard:

   • URL: https://<your-convex-url>/webhooks/polar
   • Subscribe to subscription and order events

How It Works

The Polar adapter at billing/polar/adapter.ts implements the BillingProviderAdapter interface:

• createCheckout — creates a Polar checkout session with the mapped product ID.
• createCustomerPortal — redirects to Polar's customer portal.
• cancelCurrentSubscription — cancels the active subscription via the Polar API.

Webhook Handler

The Polar webhook handler at billing/polar/webhook.ts is an HTTP action that verifies the webhook signature and processes subscription events.

Sandbox vs Production

Set POLAR_SERVER=sandbox during development to use Polar's test environment. Switch to production for live payments.

Next Reads

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