Polar billing alongside Stripe

SyntaxKit 1.1 is out. The kit can run billing through Polar as well as Stripe. You pick one provider per deployment, and the rest of the product keeps talking about plans, entitlements, and usage the same way it always has.

One switch, same product

BILLING_PROVIDER=stripe|polar selects the provider. Unset means Stripe, so an existing installation does not have to change a line of env to keep working. The shipped catalog already declares both Stripe prices and Polar products. Checkout, the portal, cancel, resume, webhook processing, reconciliation, and the support-console compare and resync paths all go through the active provider.

Polar is merchant of record. It issues invoices, receipts, and trial reminders. The kit still sends the welcome, payment-failed, and canceled emails it already owned. If you do not want both, turn off the overlapping Polar customer emails in the Polar dashboard.

What you configure

Polar needs an access token, a webhook secret, POLAR_SERVER=sandbox|production, and one Polar product id per catalog price. The webhook lands at /api/webhooks/polar and verifies Standard Webhooks signatures before anything is written. Setup doctor labels the live provider, errors if BILLING_PROVIDER is invalid or a catalog price has no id for it, and warns when the other provider's secrets are sitting in the environment unused.

A Polar sandbox live test exists behind RUN_POLAR_LIVE=1. Polar sandbox has no test clocks, so renewals and dunning stay on signed fixtures.

If you already run Stripe

Deploy the new code and apply the additive migration together. Leave BILLING_PROVIDER unset. Existing subscription rows stay Stripe. Rolling the code back is safe before or after the migration; do not drop the new columns once any Polar rows exist.

Switching BILLING_PROVIDER never migrates customers, payment methods, or subscriptions. Live rows owned by the other provider resolve to a billing-provider mismatch instead of pretending they moved. You cannot run Stripe for some organizations and Polar for others in the same deployment.

The full upgrade checklist lives in the kit at CHANGELOG.md and the Operate And Ship upgrading guide.