Administrative endpoints to manage billing subscriptions, quotas, checkout processes, and handle incoming payment notifications from Polar.
Session JWT RequiredAll billing routes except the webhook require the user’s WorkOS AuthKit session JWT. Webhooks use cryptographic signature verification.
1. Create Checkout Session
Create a checkout session for Polar plan subscriptions (e.g. Pro or Team).
Request Body
Response (200 OK)
2. Customer Portal Link
Retrieve a redirect link to the Polar customer billing portal.
Request Body
3. Retrieve Subscription
Fetch current plan configurations and quota states for the user.
Response (200 OK)
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.
Response (200 OK)
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.
Request Body
- Looks up the caller’s Polar subscription and rejects with
404 no_polar_subscription if none exists.
- Rejects with
403 plan_does_not_support_seats unless the plan is growth, pro, or enterprise.
- Calls Polar’s subscription update API with
prorationBehavior: "invoice", then mirrors the new seat_count into the local subscriptions row for immediate UI feedback.
Response (200 OK)
