Retrieve a subscription's upcoming invoice
Estimates the next invoice: fees billed up front for the next period, plus fees billed at the end and usage so far for the current one. On a trial, the conversion invoice; with a cancellation scheduled, the final invoice. Returns 404 no_upcoming_invoice for a subscription that has ended, is paused, or hasn’t started, or whose retired plan has no successor (it pauses at the boundary). Plan changes scheduled for the boundary, the next Pricing Journey step, and a plan retirement’s move to its successor are applied.
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.