Preview a subscription item change
Prices the same change PATCH /subscriptions/{subscription}/items/{item} would make, without making it. An increase is prorated and billed now (billsNow: true); a decrease waits for the next renewal and bills nothing now, or with prorationBehavior: always shows the credit for the unused time (credit) and the invoice for the rest of the period (totals), which spends that credit when it goes to the balance. 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 - 255Body
1 <= x <= 1000Overrides the default: an increase is always, a decrease or removal is next_cycle. A decrease or removal with always lands now and credits the unused time through a credit note, to the customer balance when the period's invoice is paid, off what it owes when it is open; the rest of the period on the new price is then invoiced, spending that balance. Refused when nothing billed for the period is left to credit. none applies now and bills or credits nothing.
always, none, next_cycle Remove the item instead of changing it. Waits for the next renewal unless prorationBehavior says otherwise.