Skip to main content
POST
Preview a subscription item change

Authorizations

Authorization
string
header
required

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

Idempotency-Key
string
required

Required for POST and PATCH requests. Replays identical method + path + body requests and rejects mismatched re-use.

Required string length: 1 - 255

Path Parameters

subscription
string
required
item
string
required

Body

application/json
quantity
integer
Required range: 1 <= x <= 1000
priceId
string
prorationBehavior
enum<string>

Overrides 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.

Available options:
always,
none,
next_cycle
remove
boolean

Remove the item instead of changing it. Waits for the next renewal unless prorationBehavior says otherwise.

Response

What the change would bill now.

data
object
required
meta
object
required