Preview a subscription plan change
Quotes moving the existing subscription to the requested plan and billing interval without changing anything. A more expensive plan on the same interval applies now and returns the prorated charge (per-second, before tax and discounts); cheaper plans and interval switches are scheduled for the renewal. Requires a Clerk session with a synced profile and the `billing:manage` workspace permission; the caller's pricing-experiment variant is applied.
apiKeyAuthorizationBearer <snoze_sk_…>Workspace API key created in Workspace settings → API keys. Scopes on the key bound what it can read and write.
workspaceId*stringplan*string"free""team""business""enterprise"interval*string"month""year"Success
application/json- response
data*curl -X GET 'https://api.snoze.dev/v1/workspaces/string/billing/change-plan/preview?plan=free&interval=month'{ "data": { "plan": "free", "interval": "month", "fromPlan": "free", "fromInterval": "month", "timing": "now", "effectiveAt": "string", "seats": 0, "currency": "string", "pricePerSeatCents": 0, "recurringAmountCents": 0, "renewsAt": "string", "accountBalanceCents": 0, "hasDiscount": true, "replacesScheduledChange": true, "proration": { "from": "string", "to": "string", "newPlanCents": 0, "unusedCreditCents": 0, "balanceAppliedCents": 0, "dueNowCents": 0 } }}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.
Change the workspace subscription plan
Applies a previewed plan change and returns the updated subscription. Send the preview's `timing` (`now` charges the prorated difference immediately, `period_end` schedules the change for the renewal), `dueNowCents` and `recurringAmountCents` as the customer confirmed them; the server re-quotes and rejects with a conflict when the timing or recurring amount differs or the charge due now is higher. Requires a Clerk session with a synced profile and the `billing:manage` workspace permission. Send an `Idempotency-Key` header to make retries safe.