Skip to content
Developers
Get started
Early access: these pages are being written and reviewed. Facts in the header boxes come straight from the product.

Change the subscription plan

POST
/api/v1/billing/subscription/change-plan
curl --request POST \
--url https://api.pitch2sale.com/api/v1/billing/subscription/change-plan \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "plan_slug": "example", "interval": "monthly", "seats": 1, "when": "now" }'

No proration. Upgrades and downgrades are both scheduled: the new plan takes effect on the next charge at least 48 hours away, and its features switch only after that payment succeeds (a change asked for within 48 hours of a charge applies from the following cycle). message and subscription.pending_change_note state the date. 409 new_mandate_required when the new price is above the authorised payment limit: start a new checkout with replace_current: true. 409 change_locked when a change is already locked to the next charge. Choosing the current plan drops a scheduled change (a seat change it carried stays scheduled). On a monthly per-user plan seats (optional) is the seat count on the new plan; omitted, the current or scheduled count is carried, raised to the minimum of the new plan (seats_raised_to_minimum: true). A flat-price customer moves to the per-user price and must send seats (400 seats_required). 409 too_many_users when the new plan allows fewer users than the workspace has or the seats asked for; 409 seats_below_active_users; 409 seat_not_yet_charged when the change would drop a seat that has not been paid for once. new_mandate_required carries details { plan_slug, interval, seats, charge_minor } for the new checkout. On a yearly per-user plan that has been charged, an upgrade is paid first: the answer has payment with needs_payment: true, charge_minor (the price difference for every seat for the whole days left of the year, tax included; a coupon that does not apply to the new plan is dropped), order_id and a Cashfree payment_session_id; the order is created only by this call, the plan changes only when it is paid, it expires unpaid after 48 hours (or when cancelled with DELETE /billing/orders/{id}), and the renewal is charged at the new plan (409 renewal_too_close in the last days before a renewal). A seat removal already scheduled for the renewal is kept. payment.needs_new_mandate: true when the payment authorisation does not cover the renewal of the new plan: the upgrade is still sold, subscription.review_reason becomes renewal_needs_new_mandate once it is paid, and a new checkout with replace_current: true is needed before the renewal. Every other yearly change (a downgrade, or before the first charge) is scheduled for the renewal and charges nothing now; seats cannot be added with it (409 yearly_seat_change_unavailable). Yearly to monthly (interval: monthly on a yearly subscription) answers 409 new_mandate_required with details { plan_slug, interval, seats, charge_minor, starts_at } (interval is monthly): start a new checkout with replace_current: true; monthly payments start on the renewal date. Monthly to yearly answers 409 new_mandate_required with details { plan_slug, interval, seats, charge_minor, switch_now: true, pay_now_minor, starts_at }: start a checkout with replace_current: true and switch_now: true (the switch happens when its order is paid); 409 change_locked inside the 48 hours before a monthly payment, with details.opens_at; 409 switch_to_yearly_unavailable for a lower plan or fewer seats. Upgrade now (when: "now", default next_charge): on a monthly per-user plan that has been charged, an upgrade can be taken at once. The answer has payment (as for a yearly upgrade) for the price difference for the rest of the current period, rounded down, plus tax; inside the 48 hours before a charge it also includes one whole difference, because that debit is already fixed at the old price. The amount is fixed when the order is made; the same request returns the same open order, and a different one closes it first. The plan, its features and the usage pool (for the share of the period left) move when the payment is verified, and the next charge is the new price. The order expires after 48 hours, at the period end, or when the 48 hours before the charge begin, whichever is first; a payment after that is not applied and is refunded. Under the smallest payment the provider takes (1.00) nothing is charged: the upgrade is applied and the answer has upgraded_now: true and no payment. 409 upgrade_now_unavailable for a downgrade, a yearly or never-charged subscription, or a price that is not higher; 409 new_mandate_required when the new price is above the authorised limit (authorise the new checkout first, then send the same request again to pay for the current period); 409 change_locked while the price of an earlier upgrade has not been charged yet. Owners and admins only.

Media typeapplication/json
object
plan_slug
required
string
>= 1 characters <= 50 characters
interval
required
string
Allowed values: monthly yearly
seats
integer
>= 1 <= 10000
when
string
default: next_charge
Allowed values: now next_charge

OK

Validation failed

Media typeapplication/json
object
error
required
string
code
string
message
string
details
Array<object>
object
field
required
string
message
required
string
code
required
string
Examplegenerated
{
"error": "example",
"code": "example",
"message": "example",
"details": [
{
"field": "example",
"message": "example",
"code": "example"
}
]
}

Authentication required or token invalid

Media typeapplication/json
object
error
required
string
code
string
message
string
details
Array<object>
object
field
required
string
message
required
string
code
required
string
Examplegenerated
{
"error": "example",
"code": "example",
"message": "example",
"details": [
{
"field": "example",
"message": "example",
"code": "example"
}
]
}

Role permission or token scope missing; OAuth app tokens are not accepted on this route

Media typeapplication/json
object
error
required
string
code
string
message
string
details
Array<object>
object
field
required
string
message
required
string
code
required
string
Examplegenerated
{
"error": "example",
"code": "example",
"message": "example",
"details": [
{
"field": "example",
"message": "example",
"code": "example"
}
]
}

Rate limit exceeded

Media typeapplication/json
object
error
required
string
code
string
message
string
details
Array<object>
object
field
required
string
message
required
string
code
required
string
Examplegenerated
{
"error": "example",
"code": "example",
"message": "example",
"details": [
{
"field": "example",
"message": "example",
"code": "example"
}
]
}