Preview a plan change
What POST /subscriptions/{subscription}/plan-change would do and bill, without doing it: which charges carry on, end and start, when, and the invoice it raises now. Amounts are in major units. Needs only subscriptions:read.
Authorizations
Use a Bouclay secret key (sk_test_..., sk_live_...) or restricted key
(rk_test_..., rk_live_...).
A secret key can call every endpoint. A restricted key can only call the
endpoints its scopes cover. A scope is {resource}:{access}, for example
customers:read or refunds:write, and write includes read. GET
requests need read access and everything else needs write, except
POST /subscriptions/{id}/items/{item}/preview, which only needs
subscriptions:read. A request outside the key's scopes gets 403 permission_denied naming the missing scope, and its Idempotency-Key
is not used up.
Publishable keys (pk_...) are rejected by server-side API endpoints. A
key's mode scopes what it can see and charge: a test key can never reach
a live card.
Headers
Required for POST and PATCH requests. Replays identical method + path + body requests and rejects mismatched re-use.
1 - 255Path Parameters
Body
The plan to move onto. Give this or priceId.
One of the plan's prices, which names the plan and the way to pay (and the price for its own charge when it has several). Not with planId, billingInterval or billingFrequency.
With planId, the way to pay. Omitted keeps the subscription's.
day, week, month, year Every how many intervals. Defaults to 1, or the current interval's when only this is given.
x >= 1Quantity per fixed charge of the new plan, keyed by charge id or code. A charge that carries on keeps its quantity, and a new one starts at its fewest.
Overrides the default: a change that costs the same or more in fixed fees is now, one that costs less waits for next_renewal. A longer billing interval (monthly to yearly) on a subscription of one fixed fee is now by default: the unused part of the period is credited by credit note to the balance, a new period starts today and its first invoice is charged at once, less that credit. The switch counts as the renewal: a seat count booked for the renewal is billed in the new period and used up (quantities sent with the switch replace it), and anything else booked for the renewal moves to the new one. Not while a cancel is booked: then it waits. Any other new billing interval, or a charge moving between billing at the start and at the end of the period, only works at next_renewal. While trialing, or paused off a retired plan, it is made now and bills nothing.
now, next_renewal