> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracklysms.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Current Balance

> Current account credit and its balance after known unpaid SMS and MMS usage.

Read the balance of the account associated with your API key. Authenticate with
`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

**account\_id** `integer`

The authenticated account ID.

**currency** `string`

Always `USD`.

**funded\_credit** `string`

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** `string | null`

Known unpaid SMS and MMS charges priced using settlement pricing. Null when the calculation is unavailable or usage is comped.

**net\_balance** `string | null`

`funded_credit − known_unpaid_sms`. May be negative. Null when unpaid usage cannot be calculated or usage is comped.

**as\_of** `string`

Snapshot time in ISO-8601 UTC.

**reason** `string | null`

`null` for a complete snapshot, `billing_bypass` for comped usage, or `prepaid_billing_unavailable` when the unpaid/net calculation is unavailable.

**testingBilling** `object`

Separate testing allowance and debt snapshot. Always present; fields are listed below.

`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](https://docs.tracklysms.com/api-reference/v2/messages/preflight.md) 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
with `reason: "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

```bash cURL theme={null}
curl https://api.tracklysms.com/api/v2/billing/balance \
  -H "X-Api-Key: trk_your_api_key"
```

```json Complete snapshot (200) theme={null}
{
  "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
}
```

```json Negative net balance (200) theme={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
}
```

```json Partial snapshot (200) theme={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. |

Other account/key policy errors follow the shared [error reference](https://docs.tracklysms.com/api-reference/v2/error-codes.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.