POST/organizations/{organizationId}/billing/stripe/plan
Change the Stripe plan
Operation organizations.billing.stripe.plan.change
Description
Changes the organization's active Stripe subscription from the plan at currentSeatCount (the one the administrator saw) to the plan with priceId. A larger plan is charged the prorated difference for the rest of the period immediately and its capacity applies only once that payment succeeds (upgraded); a declined or authentication-requiring payment voids its invoice, changes nothing, and returns 409 billing_plan_change_payment_failed. A smaller plan takes effect at renewal with no credit, keeping the current capacity until then (scheduled). Choosing the current plan cancels a scheduled change (kept). A current plan other than currentSeatCount, a plan that does not cover the Members roster or is not offered, an organization without a Stripe subscription that owns its capacity, a subscription that renewed into a period not yet bound, or another plan change still being applied returns 409 billing_plan_change_unavailable. Only organization administrators may call it; 502 means Stripe could not be reached and 503 that Stripe is not configured.
Authentication
Requires a signed-in session: the client sends its session token as a bearer token in the Authorization header.
Parameters
| Name | In | Type | Details |
|---|---|---|---|
organizationId | path | string | required
|
Request body
application/jsonStripePlanChangeRequest
The plan an administrator chose for the organization's active Stripe subscription.
2 fields
currentSeatCountintegerrequired- at least 1
Seat count of the plan the administrator saw when choosing. A different current plan (it renewed or changed meanwhile) gets 409
billing_plan_change_unavailable, so the choice is never charged differently than shown.priceIdstringrequired- not empty
Stripe Price id of the chosen plan, from the checkout options. It must cover the
Membersroster.
Other fields are allowed.
Responses
200 OK
application/jsonStripePlanChangeResponse
A plan change that took effect.
1 field
changestringrequired- one of
upgraded,scheduled,kept
upgradedwhen the prorated difference was paid and the larger capacity applies now,scheduledwhen the smaller plan takes effect at renewal, orkeptwhen the current plan stays, cancelling any scheduled change.- one of
Other fields are allowed.
Other responses
| Status | Meaning | Body |
|---|---|---|
| 400 | Bad Request |
|
| 401 | Unauthorized |
|
| 403 | Forbidden |
|
| 404 | Not Found |
|
| 409 | Conflict |
|
| 500 | Internal Server Error |
|
| 502 | Bad Gateway |
|
| 503 | Service Unavailable |
|