Polar is a Merchant of Record built for developers — it handles VAT, sales tax, and compliance globally while offering deep GitHub integration and low fees (4% + $0.40).
Setup
PAYMENT_PROVIDER="polar"
POLAR_ACCESS_TOKEN="your-access-token"
POLAR_WEBHOOK_SECRET="your-webhook-secret"
Get your access token from Polar Dashboard → Settings → Developers → Personal Access Tokens.
Comparison with Other Providers
| Feature | Stripe | LemonSqueezy | Polar |
|---|---|---|---|
| Tax handling | You handle (or use Stripe Tax) | Automatic (MoR) | Automatic (MoR) |
| Multi-line checkout | Yes (base plan + add-ons) | Single product | Single product |
| Customer portal | Stripe-hosted portal | LS-hosted portal | Polar purchases page |
| Connect / marketplace | Yes (Stripe Connect) | Not supported | Not supported |
| GitHub integration | None | None | License keys, GitHub App |
| Fee structure | 2.9% + $0.30 | 5% + 50¢ | 4% + $0.40 |
| Payout regions | 47 countries | 45+ countries | 100+ countries (via Stripe) |
Codapult's adapter normalizes all three providers behind the same interface, so your application code stays the same.
Webhook Setup
The Polar webhook endpoint is POST /api/webhooks/polar.
- Go to Polar Dashboard → Settings → Webhooks
- Click Add Endpoint
- Enter URL:
https://your-app.com/api/webhooks/polar - Set and save the webhook secret
- Subscribe to events:
order.created,subscription.created,subscription.updated,subscription.revoked,refund.created
Polar follows the Standard Webhooks specification. The adapter uses validateEvent from @polar-sh/sdk/webhooks for signature verification.
Local Development
Use the Polar CLI to forward webhooks to your local server:
curl -fsSL https://polar.sh/install.sh | bash
polar listen http://localhost:3000/api/webhooks/polar
Product Configuration
Create your products in the Polar Dashboard, then map them to plan IDs via environment variables:
POLAR_PRODUCT_PRO_MONTHLY="prod_..."
POLAR_PRODUCT_PRO_YEARLY="prod_..."
POLAR_PRODUCT_ENTERPRISE_MONTHLY="prod_..."
POLAR_PRODUCT_ENTERPRISE_YEARLY="prod_..."
These are read in src/lib/payments/plans.ts and used by the adapter during checkout and webhook processing.
Limitations
- No multi-line subscriptions — add-ons must be separate checkouts (same as LemonSqueezy)
- No direct quantity updates — seat-based pricing changes require a new checkout
- No pause/resume — Polar uses
revoke(immediate cancel); revoked subscriptions cannot be resumed - Customer portal — redirects to
polar.sh/purchases/subscriptions(no embedded portal)
Sandbox / Test Mode
Polar provides a sandbox environment for testing purchases, subscriptions, and refunds without real payments. Use the sandbox to trigger webhook events during development.
Environment Variables
| Variable | Required | Description |
|---|---|---|
POLAR_ACCESS_TOKEN | Yes | Personal Access Token from Polar |
POLAR_WEBHOOK_SECRET | Yes | Webhook signing secret |
For the full Polar documentation, see docs.polar.sh.