A valid request URL is required to generate request examples{
"currentPeriodEnd": "2023-11-07T05:31:56Z",
"amountMinor": 123,
"currency": "<string>",
"lineCount": 123
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "admission_unavailable",
"message": "<string>"
}
}What you owe next
The next bill: when it lands, what it comes to, and how many lines it has.
currentPeriodEnd IS THE FIELD MOST CALLERS WANT: the date a subscription renews. It is answered once for the organisation rather than once per order, deliberately: a per-order answer would cost one call to the payment provider for every row of a list, and it would have to put a renewal date on ended orders, where the honest value is never.
EVERY NUMBER HERE IS THE PAYMENT PROVIDER’S, read back and passed on unchanged. Nothing on this side computes, estimates or annualises an amount, and amountMinor is in the currency’s minor unit because that is the only form it has not been through arithmetic to reach.
NOTHING SCHEDULED IS A 200 WITH NULLS, not a 404. An organisation whose purchases are all pay as you go has no upcoming invoice, and neither has one that has ended everything; both are ordinary states of a working account and a screen should say so rather than show an error.
ANSWERS ONLY ABOUT THE CALLER’S OWN ORGANISATION. The provider’s customer reference comes off this organisation’s own purchases and never off the request.
NEEDS devices:read, the same scope GET /v1/usage needs. Money is read on the same terms as minutes: a credential narrow enough to be refused one device’s usage is not wide enough to be told what the whole organisation owes. Until 2026-09-22 this route asked only that SOME credential was present, which put the organisation-wide number behind a weaker gate than the per-device one.
Hosted deployments only. A local checkout does not mount this route, so calling it there is a 404.
A valid request URL is required to generate request examples{
"currentPeriodEnd": "2023-11-07T05:31:56Z",
"amountMinor": 123,
"currency": "<string>",
"lineCount": 123
}{
"error": {
"code": "unauthorized",
"reason": "missing_credentials",
"hint": "<string>"
}
}{
"error": {
"code": "backend_resolution_failed",
"message": "<string>",
"retryable": true
}
}{
"error": {
"code": "rate_limited",
"message": "<string>"
}
}{
"error": {
"code": "admission_unavailable",
"message": "<string>"
}
}Authorizations
The control surface credential. Send Authorization: Bearer <token>.
Two kinds of token are accepted and they are told apart by shape, not by a separate header. A token beginning pbk_ is an org scoped API key, whose public half and secret half are generated together and of which only a hash of the secret is ever stored; anything else is treated as an OAuth 2.1 access token and verified against the authorization server's keys.
Both resolve to the same context: an org, a principal and a set of scopes. Nothing downstream branches on which channel you used, with one deliberate exception, key management, which requires a signed-in person so that a key can never mint another key.
Scopes are enforced when MCP tools are REGISTERED rather than when they are called, so a tool your credential cannot use is absent from tools/list rather than refused mid gesture.
Response
What is due next, or nulls when nothing is scheduled.
What this organisation owes next, as the payment provider states it.
When the period now running ends, which is when the next bill lands. Null when nothing is scheduled: an organisation whose purchases are all pay as you go has no upcoming invoice, and neither has one that has ended everything.
The total, in the currency's MINOR unit, exactly as the payment provider states it. Nothing on this side computes, estimates or annualises it. Null when nothing is scheduled.
ISO 4217, lower case. Null when nothing is scheduled.
How many lines the next bill has, in ROWS. Zero when nothing is scheduled.