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.

Preview a plan change

GET
/api/v1/billing/subscription/change-plan/preview
curl --request GET \
--url 'https://api.pitch2sale.com/api/v1/billing/subscription/change-plan/preview?plan_slug=example&interval=monthly' \
--header 'Authorization: Bearer <token>'

What POST /billing/subscription/change-plan would do for plan_slug, interval and optional seats (query). Nothing is written and Cashfree is not called. Returns kind (upgrade or downgrade), applies (next_charge, charge_after_next inside the 48 hours before a charge, renewal on a yearly plan, or on_payment for a paid yearly upgrade), effective_at, seats on the new plan (null for a flat price), seats_raised_to_minimum, charge_minor (the recurring charge on the new plan, tax included), currency, pay_now_minor (a yearly upgrade: what is paid now for the rest of the year, tax included; null otherwise), needs_checkout (true when the new price is above the authorised payment limit, for yearly to monthly, and for monthly to yearly, where pay_now_minor is what the switch order would ask for now; with pay_now_minor the upgrade is still sold and the new checkout is needed before the renewal), leaves_flat_price (a flat-price customer moves to the per-user price for good) and blocked (too_many_users, change_locked or null; charge_minor is 0 when blocked). upgrade_now is what when: "now" would cost on a monthly plan, or null when it is not offered: pay_now_minor (tax included), net_minor, tax_minor, covers_from, covers_to and includes_next_period (true inside the 48 hours before a charge). Other refusals answer as the POST does. The preview never creates an order. Requires settings.edit; owners and admins only.

plan_slug
required
string
>= 1 characters <= 50 characters
interval
required
string
Allowed values: monthly yearly
seats
integer
>= 1 <= 10000

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