curl https://api.tracklysms.com/api/v2/billing/balance \
-H "X-Api-Key: trk_your_api_key"
{
"account_id": 1042,
"currency": "USD",
"funded_credit": "250.00",
"known_unpaid_sms": "35.00",
"net_balance": "215.00",
"as_of": "2026-11-02T15:00:00Z",
"reason": null
}
{
"account_id": 1042,
"currency": "USD",
"funded_credit": "10.00",
"known_unpaid_sms": "35.00",
"net_balance": "-25.00",
"as_of": "2026-11-02T15:00:00Z",
"reason": null
}
{
"account_id": 1042,
"currency": "USD",
"funded_credit": "250.00",
"known_unpaid_sms": null,
"net_balance": null,
"as_of": "2026-11-02T15:00:00Z",
"reason": "prepaid_billing_unavailable"
}
Usage & Billing (v2)
Get Current Balance
Current account credit and its balance after known unpaid SMS and MMS usage.
GET
/
v2
/
billing
/
balance
curl https://api.tracklysms.com/api/v2/billing/balance \
-H "X-Api-Key: trk_your_api_key"
{
"account_id": 1042,
"currency": "USD",
"funded_credit": "250.00",
"known_unpaid_sms": "35.00",
"net_balance": "215.00",
"as_of": "2026-11-02T15:00:00Z",
"reason": null
}
{
"account_id": 1042,
"currency": "USD",
"funded_credit": "10.00",
"known_unpaid_sms": "35.00",
"net_balance": "-25.00",
"as_of": "2026-11-02T15:00:00Z",
"reason": null
}
{
"account_id": 1042,
"currency": "USD",
"funded_credit": "250.00",
"known_unpaid_sms": null,
"net_balance": null,
"as_of": "2026-11-02T15:00:00Z",
"reason": "prepaid_billing_unavailable"
}
Read the balance of the account associated with your API key. Authenticate with
Other account/key policy errors follow the shared error reference.
X-Api-Key and the usage.read permission, following the same authorization
rules as the other billing reads.
This endpoint accepts no body, account-selection, billing-period, or pagination
parameters. A parent key reads its own account; use a child’s key to read that
child’s balance. Account-selection query parameters do not change the account.
Responses use Cache-Control: no-store.
Response Fields
Remaining account credit after posted deductions, formatted with two decimal places. Includes credit added by staff and confirmed prepaid funding; excludes any overdraft allowance.
Known unpaid SMS and MMS charges priced using settlement pricing. Null when the calculation is unavailable or usage is comped.
funded_credit − known_unpaid_sms. May be negative. Null when unpaid usage cannot be calculated or usage is comped.null for a complete snapshot, billing_bypass for comped usage, or prepaid_billing_unavailable when the unpaid/net calculation is unavailable.testingBilling contains enabled and previouslyEnabled booleans; endedAt
(ISO-8601 UTC or null); limitUsd, accruedUsd, unbilledUsd,
reservedFeeUsd, and exposureUsd USD decimal strings (nullable except
limitUsd); sendingPaused boolean; reason string or null; and asOf
ISO-8601 UTC time. Unavailable amounts are null, never assumed zero.
Monetary values are decimal strings, including confirmed zero ("0.00").
An unavailable calculation is null, never an assumed zero.
On an existing billing configuration, an unset credit field uses its defined
zero-credit default when calculating unpaid usage and net balance. This default
does not write a balance to the account. An account without a billing configuration
returns 404. Funded credit must be nonnegative and an exact whole-cent amount:
invalid stored amounts, including sub-cent credit such as -0.001, return
503 balance_unavailable before any rounding.
Balance Meaning and Availability
The net balance includes known unpaid SMS/MMS usage only. Provider costs still arriving and other product liabilities are excluded. Overdraft capacity is not funded credit. A positive balance does not establish permission to send: use send preflight to check eligibility. Complete net calculations support ordinary self-paying accounts, including custom usage tiers. Accounts with pooled or commercial pricing, parent-paid accounts, and accounts awaiting settlement/debit/audit reconciliation receive readable funded credit with null unpaid and net amounts. Legacy special pricing also receives this partial response. A parent-paid account never receives its parent’s credit balance. For billing-bypass accounts, usage is comped: the response shows funded credit withreason: "billing_bypass" and null unpaid/net amounts. Comped usage is
never presented as debt. Reading a balance does not charge the account or change
its SMS pause state.
For active or previously enabled testing billing, funded_credit remains
readable, while known_unpaid_sms and net_balance are null with
reason: "prepaid_billing_unavailable". Read unpaid testing debt and its
separate send allowance from testingBilling; do not subtract it from funded
credit.
Examples
curl https://api.tracklysms.com/api/v2/billing/balance \
-H "X-Api-Key: trk_your_api_key"
{
"account_id": 1042,
"currency": "USD",
"funded_credit": "250.00",
"known_unpaid_sms": "35.00",
"net_balance": "215.00",
"as_of": "2026-11-02T15:00:00Z",
"reason": null
}
{
"account_id": 1042,
"currency": "USD",
"funded_credit": "10.00",
"known_unpaid_sms": "35.00",
"net_balance": "-25.00",
"as_of": "2026-11-02T15:00:00Z",
"reason": null
}
{
"account_id": 1042,
"currency": "USD",
"funded_credit": "250.00",
"known_unpaid_sms": null,
"net_balance": null,
"as_of": "2026-11-02T15:00:00Z",
"reason": "prepaid_billing_unavailable"
}
Error Codes
| HTTP Status | Error Code | Description |
|---|---|---|
| 401 | invalid_credentials | The credential is missing or invalid. |
| 403 | insufficient_scope | The credential lacks billing-read authority under the active authorization policy. |
| 403 | account_suspended | The account or its parent cannot use the API. |
| 404 | billing_not_configured | This account has no billing configuration. |
| 503 | balance_unavailable | Funded credit cannot be read reliably or its stored amount is invalid. Retry the read with backoff. |