API reference

Carrier balances

Read and adjust a customer account's prepaid wallet — view the balance, top up, debit, and list transactions.

Balance resource

Each account has a single wallet. All usage — voice calls, SMS, recordings, transcription, AI usage, verification and phone numbers — draws from this one balance. The category field on transactions still records which product line a charge belongs to for reporting.

Balancejson

{
  "data": [
    {
      "category": "general",
      "balance_cents": "1750000",
      "currency": "NGN"
    }
  ]
}

Transaction categories

Category	Used for
`voice`	Call usage.
`sms`	Message usage.
`recording`	Call recording.
`ai`	AI usage (LLM, TTS, STT / transcription).
`verification`	Verification attempts.
`phone_number`	Monthly number fees.
`general`	The account's single wallet balance.

Read balances

GET/carrier/v1/accounts/{account_id}/balances

Return the account's wallet balance.

Top up

POST/carrier/v1/accounts/{account_id}/balances/top_up

Add credit to the account wallet.

Parameter	Type	Description
`category` required	`string`	Product line for the ledger (voice, sms, ai, ...). The credit always lands in the single wallet.
`amount_cents` required	`integer`	Amount to add in minor units.
`description` optional	`string`	Optional memo.

Debit

POST/carrier/v1/accounts/{account_id}/balances/debit

Manually deduct from the account wallet (e.g. for a refund or correction).

Parameter	Type	Description
`category` required	`string`	Product line for the ledger (voice, sms, ai, ...).
`amount_cents` required	`integer`	Amount to deduct in minor units.
`description` optional	`string`	Optional memo.

Transactions

GET/carrier/v1/accounts/{account_id}/balances/transactions

List the account's balance transactions.

Parameter	Type	Description
`category` optional	`string`	Restrict to a product-line category.
`limit` optional	`integer`	Max transactions to return (default 50).

Top-ups, debits and usage charges are audited as transactions. Every adjustment appears in transactions with a timestamp and description.