Balance — FiscalRail documentation

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 when an immutable ledger of credits and debits is required.

The Balance object

Properties

id string

Opaque identifier for a balance.

object string

String identifying this as a Balance object. Always balance.

live boolean

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

account string

Live account that owns the balance.

amount string

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

currency enum

Billing currency for the balance.

Possible values

EUR

updated_at string

When the balance last changed.

Balance object

{
  "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. JSON

Example request

  import os

from fiscalrail import FiscalRail

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

balance = client.balances.retrieve()

  require "fiscalrail"

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

balance = client.balances.retrieve

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

Example response — 200

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