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.

Add or remove seats

POST
/api/v1/billing/seats
curl --request POST \
--url https://api.pitch2sale.com/api/v1/billing/seats \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "seats": 1 }'

Changes the seat count (seats) of a per-user subscription. Nothing is charged or refunded now and the current charge never changes: the new amount applies from the next charge at least 48 hours away (a change asked for within 48 hours of a charge applies from the following one). An added seat can be used at once. A removed seat needs its user deactivated first (409 seats_below_active_users) and at least one payment (409 seat_not_yet_charged); while a removal is scheduled the freed seat cannot be filled again. Returns seats (paid now), pending_seats, effective_at, charge_note and needs_checkout: true means the payment authorisation does not cover that many seats, nothing was scheduled, and a new checkout with replace_current: true is needed. On a yearly plan that has been charged, added seats are paid first: the answer has needs_payment: true, charge_minor (the added seats for the whole days left of the year, tax included), order_id and a Cashfree payment_session_id; the seats are added only when that order is paid, the order expires unpaid after 48 hours, and the renewal is charged for the new seat count (409 renewal_too_close in the last days before a renewal or before the first yearly charge; 409 yearly_seat_change_unavailable when the payment authorisation does not cover the seats: contact support). A removal on a yearly plan applies at the renewal, with no refund. 409 seats_not_available on a flat-price subscription; 409 change_locked when a change is already locked to the next charge. Owners and admins only; 10 billing changes per hour per organization.

Media typeapplication/json
object
seats
required
integer
>= 1 <= 10000
Examplegenerated
{
"seats": 1
}

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"
}
]
}