Billing API

Balance

GET/v1/billing/balance

Response

Field	Type	Notes
`object`required	"credit_balance"
`organization_id`required	string
`balance_brl`required	string
`currency`required	"brl"
`updated_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$

Current rate card

GET/v1/rate-cards/current

Response

Field	Type	Notes
`id`required	string
`object`required	"rate_card"
`name`required	string
`currency`required	"brl"
`effective_from`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`effective_to`required	string<ISO-8601> \| null
`entries`required	object[]

Ledger

GET/v1/billing/ledger

Response

Field	Type	Notes
`object`required	"list"
`data`required	object[]
`has_more`required	boolean
`next_cursor`required	string \| null

Entry shape

Field	Type	Notes
`id`required	string
`object`required	"ledger_entry"
`type`required	"debit" \| "credit"
`source_type`required	"usage" \| "credit_topup"
`source_id`required	string
`meter_id`required	string \| null
`amount_brl`required	string
`uncollected_brl`required	string \| null
`currency`required	"brl"
`environment`required	"sandbox" \| "production" \| null
`recorded_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$
`trace_id`required	string \| null

Self-serve billing endpoints

Credit packages (GET /v1/billing/packages, POST /v1/billing/packages/purchase), saved payment methods (GET/POST /v1/billing/payment-methods, setup-intent, default, DELETE), auto top-up (GET/PUT /v1/billing/auto-topup), and the full rate-card list (GET /v1/rate-cards) are public API endpoints documented in /openapi.json. Writes require billing:write.

Dashboard-only billing actions

Custom-amount top-ups, invoice builds, and spend-limit updates are dashboard control-plane workflows, not public customer API endpoints. They are intentionally excluded from /openapi.json.

Invoices

GET/v1/invoices

Response

Field	Type	Notes
`object`required	"list"
`data`required	object[]
`has_more`required	boolean
`next_cursor`required	string \| null

GET/v1/invoices/{'{id}'}/download

Response

Field	Type	Notes
`object`required	"invoice_download"
`invoice_id`required	string
`url`required	string
`expires_at`required	string<ISO-8601>	pattern: ^(?:(?:\d\d[2468][048]\|\d\d[13579][26]\|\d\d0[48]\|[02468][048]00\|[13579][26]00)-02-29\|\d{4}-(?:(?:0[13578]\|1[02])-(?:0[1-9]\|[12]\d\|3[01])\|(?:0[469]\|11)-(?:0[1-9]\|[12]\d\|30)\|(?:02)-(?:0[1-9]\|1\d\|2[0-8])))T(?:(?:[01]\d\|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z\|([+-](?:[01]\d\|2[0-3]):[0-5]\d)))$