Skip to main content

ChangePlan changes the subscription to a different plan with proration.

POST 
/api/v1/billing/subscription/change-plan

Switches the organization to a new plan, calculating prorated credits/charges for the remaining billing period. Can be applied immediately or at period end.

Authorization​

Requires billing:manage permission.

Proration Calculation​

When immediate=true:

  • Credit: (old_plan_price * days_remaining) / total_days
  • Charge: (new_plan_price * days_remaining) / total_days
  • Net: charge - credit (positive = additional charge, negative = credit)

Behavior​

  • immediate=true: Plan changes now, invoice/credit generated for proration
  • immediate=false: Plan changes at next billing period (no proration)
  • Subscription items may need adjustment if new plan has different limits

Response​

Returns updated Subscription and ProrationDetails showing the financial impact.

Errors​

  • NOT_FOUND: Subscription or new plan does not exist
  • INVALID_ARGUMENT: new_plan_id same as current plan
  • FAILED_PRECONDITION: Current usage exceeds new plan limits
  • PERMISSION_DENIED: Caller lacks billing:manage permission

Request​

Responses​

A successful response.