1. Create Checkout Session
Create a checkout session for Polar plan subscriptions (e.g. Pro or Team).2. Customer Portal Link
Retrieve a redirect link to the Polar customer billing portal.3. Retrieve Subscription
Fetch current plan configurations and quota states for the user.quota_sync_ops, quota_storage_bytes, and quota_subkeys are not currently enforced as differentiators — every plan carries an effectively unlimited value for these three. The quotas that actually vary by plan are quota_devices (3 on Hobby, up to unlimited on Enterprise) and seats (seat_count / included_seats, Growth and Pro plans only — see Update Seats).4. Retrieve Usage Metrics
Retrieve cumulative usage statistics across all of the user’s API keys for the current billing cycle.5. Polar Webhook Handler
Receives cryptographically signed webhook calls from Polar to update user subscriptions on the fly.- Security: Signature verification using Standard Webhooks HMAC. Rejects missing or invalid signatures with
403 invalid_webhook_signature. - Events Handled:
subscription.created/subscription.active— Upsert active plan and reset quotas.subscription.updated— Sync period boundaries and subscription statuses.subscription.canceled/subscription.revoked— Reset status to canceled, drop quotas back to the Free plan.
6. Update Seats
Change the seat count on a team subscription. Growth, Pro, and Enterprise plans only — the request is rejected on any other plan.- Looks up the caller’s Polar subscription and rejects with
404 no_polar_subscriptionif none exists. - Rejects with
403 plan_does_not_support_seatsunless the plan isgrowth,pro, orenterprise. - Calls Polar’s subscription update API with
prorationBehavior: "invoice", then mirrors the newseat_countinto the localsubscriptionsrow for immediate UI feedback.