A valid request URL is required to generate request examples{}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Change my team's plan
The self-serve upgrade or downgrade: moves the team’s subscription onto a different live price — now, or when the current period ends. Owner-only.
subscription_id names which subscription when the team holds more than one; omitted, the single active one answers, and several answer 409 asking to be named — declared when it is ambiguous, derived when it is not.
The target price is the public read’s, exactly as the checkout’s is. On a per_seat price the quantity is the team’s member count, derived here as it is everywhere. at_period_end and prorate behave as they do on the staff surface, capability-checked with a 501 rather than downgraded: an immediate charge is not a degraded version of a scheduled one.
Nothing is written optimistically — the gateway decides, the mirror is re-read after it accepts, and mirror_refreshed says whether the body is the gateway’s word.
A valid request URL is required to generate request examples{}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}{
"error": {
"code": "forbidden",
"message": "your role does not allow this action"
}
}Autorizações
A contact session token, uk_ct_…. Belongs to one of the developer's own users, and reads only that user's data.
Cabeçalhos
The customer this call is acting inside — the same arrangement as X-Organization-Id, one plane down. Switching customers is navigation, not a mutation: nothing is stored, you send a different header, and the membership JOIN behind it decides what you may do there. An id you are not a member of matches no row and answers 404. Absent, the contact's oldest membership answers.
Forwarded to the payment gateway as its idempotency key, so a retry of this call does not charge twice or move a subscription twice.
This is not the guarantee Idempotency-Key carries on the API-key surface: nothing is stored here and a replay is not answered with the original response. It is passed through, and what it buys is whatever the gateway does with it — for Stripe, the original result is replayed for 24 hours.
Send a fresh key per act you mean to perform, and the same key with the same body when you are retrying one. The gateway compares the parameters, so a key reused for a different act is refused there rather than replayed.
255Corpo
The live price to move onto. Recurring only.
Which subscription, when the team holds several.
Wait for the current period to end. Needs the gateway's scheduled_plan_change.
Credit or charge the difference now. Needs the gateway's proration. Defaults false so an omitted field cannot charge a card today.
Resposta
The subscription as it now stands, re-read from the gateway, with mirror_refreshed and mirror_stale_reason declared as they are on the staff surface.
The response is of type object.