Change the workspace subscription plan
Moves the existing subscription to the requested plan and billing interval in place, then returns the resulting subscription. Requires a Clerk session with a synced profile and the `billing:manage` workspace permission; the caller's pricing-experiment variant is applied so the price matches the catalog they were shown.
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/change-plan" \ -H "Content-Type: application/json" \ -d '{ "plan": "free", "interval": "month" }'{ "data": { "workspaceId": "string", "plan": "free", "status": "none", "polarCustomerId": "string", "polarSubscriptionId": "string", "polarProductId": "string", "cancelAtPeriodEnd": true, "currentPeriodEnd": "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 detailed billing record for a workspace
Returns the expanded billing detail behind the subscription summary. Requires a Clerk session and the `billing:read` workspace permission.
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.