Operation details
GET /v1/admin/billing/accounts
List tenant balances for manual administration
- operationId
listBillingAccounts- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires billing.adjustments.manage in a platform scope. Accounts without entries are returned with a zero balance and revision one.
Parameters
listBillingAccounts Parameters| Name | In | Type | Required | Description |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
search | query | string | No | — |
|---|
scope_ids | query | array<string(uuid)> | No | Optional comma-separated set of 1–100 distinct canonical, nonzero tenant scope UUIDs. Intersects the existing search and active-tenant filters before pagination. Unknown, platform and inactive scopes produce no rows; omission preserves the unfiltered behavior. Requires the same billing.adjustments.manage permission as the account list. Reading never creates accounts or postings. |
|---|
Responses
listBillingAccounts Responses| Status | Description |
|---|
200 | Tenant balance page ordered by tenant name. Fields：items: array<BillingAccount> total: integer(int64) page: integer limit: integer |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/admin/billing/accounts/{id}/ledger
List immutable entries for a selected tenant balance
- operationId
listBillingAccountLedger- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires billing.adjustments.manage in a platform scope. The identifier must resolve to a tenant billing account; a valid tenant account with no postings returns an empty page.
Parameters
listBillingAccountLedger Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
Responses
listBillingAccountLedger Responses| Status | Description |
|---|
200 | Newest-first ledger page for the selected tenant account. Fields：items: array<BillingLedgerEntry> total: integer(int64) page: integer limit: integer |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/admin/billing/adjustments
List manual billing adjustment approval requests
- operationId
listBillingAdjustments- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires billing.adjustments.propose or billing.adjustments.approve in a platform scope. Pending and expired are derived from the immutable proposal expiry when no terminal decision exists.
Parameters
listBillingAdjustments Parameters| Name | In | Type | Required | Description |
|---|
page | query | integer | No | — |
|---|
limit | query | integer | No | — |
|---|
state | query | string: pending / approved / rejected / cancelled / expired | No | — |
|---|
Responses
listBillingAdjustments Responses| Status | Description |
|---|
200 | Newest-first immutable adjustment request page. Fields：items: array<BillingAdjustment> total: integer(int64) page: integer limit: integer |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/admin/billing/adjustments
Propose an MFA-bound manual tenant balance adjustment
- operationId
proposeBillingAdjustment- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires billing.adjustments.propose in a platform scope and a max_uses=1 MFA proof bound to the proposal. This operation never changes a balance; a different operator must approve it.
Parameters
proposeBillingAdjustment Parameters| Name | In | Type | Required | Description |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
proposeBillingAdjustment Request body| Name | Type | Required | Description |
|---|
account_id | string(uuid) | Yes | — |
|---|
direction | string: credit / debit | Yes | — |
|---|
amount_minor | integer(int64) | Yes | — |
|---|
reason | string | Yes | — |
|---|
expected_account_revision | integer(int64) | Yes | — |
|---|
step_up_token | string | Yes | — |
|---|
Responses
proposeBillingAdjustment Responses| Status | Description |
|---|
201 | Immutable pending proposal created, or the exact stored response replayed. Fields：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
500 | The request could not be completed because of an internal failure. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.500 Outcome unknown: read back by ID or list first, then decide whether to retry with the original Idempotency-Key.
↑ Back to list
GET /v1/admin/billing/adjustments/{id}
Read one billing adjustment approval request
- operationId
getBillingAdjustment- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
getBillingAdjustment Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
Responses
getBillingAdjustment Responses| Status | Description |
|---|
200 | Current immutable proposal and optional terminal decision. Fields：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/admin/billing/adjustments/{id}/approve
Approve and atomically post another operator's adjustment
- operationId
approveBillingAdjustment- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Description (from the contract)
Requires billing.adjustments.approve, If-Match revision one, and a separate max_uses=1 MFA proof. Proposal, decision, double-entry postings, balance, audit, and replay receipt commit atomically.
Parameters
approveBillingAdjustment Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
approveBillingAdjustment Request body| Name | Type | Required | Description |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
step_up_token | string | Yes | — |
|---|
Responses
approveBillingAdjustment Responses| Status | Description |
|---|
200 | Approved terminal request or exact stored replay. Fields：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/admin/billing/adjustments/{id}/cancel
Cancel a pending adjustment from the original proposal session
- operationId
cancelBillingAdjustment- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
cancelBillingAdjustment Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
cancelBillingAdjustment Request body| Name | Type | Required | Description |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
Responses
cancelBillingAdjustment Responses| Status | Description |
|---|
200 | Cancelled terminal request or exact stored replay. Fields：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list
POST /v1/admin/billing/adjustments/{id}/reject
Reject another operator's adjustment
- operationId
rejectBillingAdjustment- Auth
- Session: the Bearer session of a signed-in control plane user, used by the customer in their own control plane; a plugin must never ask for it.
- Required permissions
The contract has no separate permission annotation; see the description below and the 403 response.
Parameters
rejectBillingAdjustment Parameters| Name | In | Type | Required | Description |
|---|
id | path | string(uuid) | Yes | — |
|---|
If-Match | header | string | Yes | — |
|---|
Idempotency-Key | header | string | Yes | — |
|---|
Request body
application/json · Required：Yes
rejectBillingAdjustment Request body| Name | Type | Required | Description |
|---|
expected_revision | integer(int64) | Yes | — |
|---|
step_up_token | string | Yes | — |
|---|
Responses
rejectBillingAdjustment Responses| Status | Description |
|---|
200 | Rejected terminal request or exact stored replay. Fields：id: string(uuid) target_scope_id: string(uuid) target_tenant_id: string(uuid) target_account_id: string(uuid) direction: string: credit / debit amount_minor: integer(int64) currency: string reason: string expected_account_revision: integer(int64) state: string: pending / approved / rejected / cancelled / expired revision: integer(int64) proposed_by_scope_id: string(uuid) proposed_by_user_id: string(uuid) proposed_at: string(date-time) expires_at: string(date-time) decision?: BillingAdjustmentDecision |
|---|
400 | The request body or parameters are invalid. |
|---|
401 | Authentication failed or the session is invalid. |
|---|
403 | The authenticated principal is not allowed to perform the action. |
|---|
404 | The requested resource was not found. |
|---|
409 | The requested state conflicts with an existing resource or idempotency fact. |
|---|
415 | Content-Type must be exactly application/json without parameters. |
|---|
503 | A required dependency is unavailable. |
|---|
What to do on failure
400 Fix the parameters or body per the field list; do not retry unchanged.401 Check the credential format and whether it expired or was rotated.403 Check the key scopes, the owner’s current permissions and the tenant scope; never switch to a more privileged account.404 The resource does not exist or belongs to another tenant.409 Read the current state first; a retry of the same operation keeps the original Idempotency-Key and body.503 A dependency is unavailable: retry later with the original Idempotency-Key.
↑ Back to list