Polar Setup

Bklit uses Polar.sh for billing and subscription management. This guide covers setting up Polar for your Bklit instance.

Polar is Optional: You only need Polar.sh if you want to charge for subscriptions. Without Polar, all users have free tier access. Core analytics features work without billing.

Already Set Up? The npx @bklit/create wizard can configure Polar for you during initial setup.

Prerequisites

Polar.sh account
Polar organization created
API access token

Step 1: Create Polar Account

Go to polar.sh
Sign up for an account
Create an organization

Step 2: Get API Credentials

Access Token

Go to Polar dashboard
Navigate to Settings → API
Generate an access token
Copy the token (save it securely)

Organization ID

Go to Polar dashboard
Navigate to Settings → Organization
Copy your Organization ID

Webhook Secret

Go to Polar dashboard
Navigate to Settings → Webhooks
Create a webhook endpoint
Copy the webhook secret

Step 3: Create Products

Pro Plan Product

Go to Products in Polar dashboard
Click "Create Product"
Set up subscription product:
- Name: "Bklit Pro"
- Type: Subscription
- Price: Set your price
- Billing period: Monthly/Yearly
Copy the Product ID

Free Plan Product (Optional)

If you want a free plan in Polar:

Create a product with $0 price
Copy the Product ID
Set in POLAR_FREE_PRODUCT_ID

Step 4: Configure Environment Variables

Add to your .env file:

# Polar Configuration
POLAR_ACCESS_TOKEN="your-polar-access-token"
POLAR_SERVER_MODE="sandbox"  # or "production"
POLAR_WEBHOOK_SECRET="your-webhook-secret"
POLAR_ORGANIZATION_ID="your-organization-id"
POLAR_PRO_PRODUCT_ID="your-pro-product-id"
NEXT_PUBLIC_POLAR_PRO_PLAN_PRODUCT_ID="your-pro-product-id"  # Same as above
POLAR_FREE_PRODUCT_ID="your-free-product-id"  # Optional

Step 5: Set Up Webhooks

Webhook Endpoint

Your webhook endpoint should be:

https://your-domain.com/api/webhooks/polar

Configure in Polar

Go to Polar dashboard
Navigate to Settings → Webhooks
Add webhook endpoint:
- URL: https://your-domain.com/api/webhooks/polar
- Secret: Your webhook secret
- Events: Subscribe to subscription events

Required Events

Subscribe to these events:

subscription.created
subscription.updated
subscription.canceled
subscription.revoked

Local Development with Webhooks

Why You Need a Tunnel

Polar webhooks can't reach localhost. To test webhooks locally, expose your server with a tunnel.

Using ngrok (Recommended)

1. Install ngrok:

Visit https://ngrok.com/download
Follow installation instructions

2. Start services:

# Terminal 1: Your app
pnpm dev

# Terminal 2: ngrok
ngrok http 3000

3. Configure webhook in Polar:

Copy ngrok HTTPS URL: https://abc123.ngrok.io
In Polar dashboard → Settings → Webhooks
Webhook URL: https://abc123.ngrok.io/api/webhooks/polar
Secret: Your POLAR_WEBHOOK_SECRET from .env

4. Test subscription:

Create test subscription in Polar sandbox
Check webhook delivery in Polar logs
Verify organization plan updates in your dashboard

Alternative: Cloudflare Tunnel

cloudflared tunnel --url http://localhost:3000

Use: https://abc123.trycloudflare.com/api/webhooks/polar

Important Notes

Free ngrok URLs change on restart - Update Polar webhook URL when restarting
Use sandbox mode: POLAR_SERVER_MODE="sandbox" for local dev
Optional for basic dev - Webhooks only needed for subscription testing
Production uses your domain - No tunnels needed in production

For complete local development setup: Local Development