# Balance

Inspect the prepaid credit available to a Live account.

Each Live account has a prepaid balance used for paid FiscalRail operations. The
amount is returned as a decimal string in the currency's major unit and may be
negative after the operation that uses the last available credit.

Test accounts do not hold balances. Retrieving a balance for a Test account
returns `404 resource_not_found` because no Balance resource exists for it.

Balance reads are informational. Another operation may consume credit after a
read, so clients must still handle `402 balance_exhausted` as the authoritative
issuance result. Top-ups remain available through the FiscalRail dashboard.

Every balance movement also creates a `billing.balance_transaction.created`
Event. Use the [Events reference](/en/api/events) when an immutable ledger of
credits and debits is required.

## The Balance object

### Properties

#### `id`

Type: `string`

Opaque identifier for a balance.

#### `object`

Type: `string`

String identifying this as a Balance object. Always `balance`.

#### `live`

Type: `boolean`

True when the object belongs to the live environment; false for test data.

#### `account`

Type: `string`

Live account that owns the balance.

#### `amount`

Type: `string`

Current signed balance in the currency's major unit. This amount is informational and may change before the next paid operation.

#### `currency`

Type: `enum`

Billing currency for the balance.

Possible values:

- `EUR` — 

#### `updated_at`

Type: `string`

When the balance last changed.


### Example

```json
{
  "id": "bal_14Vxtqg2nwvPR75TpsGH8N",
  "object": "balance",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "amount": "12.50",
  "currency": "EUR",
  "updated_at": "2026-08-25T16:00:00Z"
}
```

## Retrieve a balance

`GET /v1/account/balance`

Returns the current prepaid balance for a Live account. Test accounts do not have Balance resources. The amount is informational; clients must still handle balance exhaustion when performing a paid operation.

### Responses

- `200` — [A Balance object.](#the-balance-object) Formats: JSON.

### Example requests

#### Python

```python
import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

balance = client.balances.retrieve()
```

#### Ruby

```ruby
require "fiscalrail"

client = FiscalRail::Client.new(api_key: ENV.fetch("FISCALRAIL_API_KEY"))

balance = client.balances.retrieve
```

#### cURL

```bash
curl --request GET \
  'https://api.fiscalrail.com/v1/account/balance' \
  --header "Authorization: Bearer fra_test_..."
```

### Example response — 200

```json
{
  "id": "bal_14Vxtqg2nwvPR75TpsGH8N",
  "object": "balance",
  "live": true,
  "account": "acct_14Vxtqg2nwvPR75TpsGH8N",
  "amount": "12.50",
  "currency": "EUR",
  "updated_at": "2026-08-25T16:00:00Z"
}
```