Open a hosted checkout session for a plan
Creates a Polar checkout session for the requested plan and interval, sized to the workspace's current seat count, and returns the hosted URL to redirect to. Requires a Clerk session with a synced profile and the `billing:manage` workspace permission; opening checkout also records a pricing-experiment exposure so a direct link is attributed like a catalog view.
Authorization
apiKey Workspace API key created in Workspace settings → API keys. Scopes on the key bound what it can read and write.
In: header
Path Parameters
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/v1/workspaces/string/billing/checkout" \ -H "Content-Type: application/json" \ -d '{ "plan": "free", "interval": "month" }'{ "data": { "id": "string", "url": "string" }}{ "_tag": "ApiNotFound", "error": "not_found", "message": "That item does not exist, or this key cannot see it.", "status": 404}{ "_tag": "ApiNotFound", "error": "not_found", "message": "That item does not exist, or this key cannot see it.", "status": 404}Read the workspace usage breakdown
Returns per-resource usage counts for the workspace. Deliberately open to any workspace member rather than gated on `billing:read`, because these counts are what the interface uses to explain why a limit-bound action is unavailable.
Open a hosted checkout session for an AI top-up pack
Creates a Polar checkout session for a prepaid AI top-up pack; the balance is credited later by the order webhook, not by this call. Requires a Clerk session with a synced profile and the `billing:manage` workspace permission, and is refused as forbidden when the workspace's usage snapshot reports that top-ups are not available on its current plan.