Skip to main content
Retrieves a specific balance by its unique identifier. Returns the complete balance record including current amounts, version information, and optionally related data.

​
Path Parameters

​
id
string
required
The unique identifier of the balance to retrieve.

​
Query Parameters

​
include
array
Additional related data to include in the response. Can specify multiple values.Options:
  • identity: Include the full identity object
  • ledger: Include the full ledger object
Example: ?include=identity&include=ledger
​
with_queued
boolean
default:"false"
Include queued transaction amounts in the balance response.When enabled, adds:
  • queued_debit_balance: Amount in queued debit transactions
  • queued_credit_balance: Amount in queued credit transactions
Example: ?with_queued=true

​
Response

​
balance_id
string
Unique identifier for the balance.
​
ledger_id
string
The ledger ID this balance belongs to.
​
identity_id
string
The identity ID associated with this balance.
​
indicator
string
Optional indicator value for retrieving balance by a custom identifier (e.g., phone number, email).
​
currency
string
The currency code for this balance.
​
balance
string
The current balance amount (credit_balance - debit_balance). Returned as a big integer string.
​
credit_balance
string
Total credits applied to this balance.
​
debit_balance
string
Total debits applied to this balance.
​
inflight_balance
string
Total balance currently in inflight transactions.
​
inflight_credit_balance
string
Credits currently in inflight status.
​
inflight_debit_balance
string
Debits currently in inflight status.
​
queued_debit_balance
string
Amount in queued debit transactions. Only included when with_queued=true.
​
queued_credit_balance
string
Amount in queued credit transactions. Only included when with_queued=true.
​
currency_multiplier
float
The precision multiplier for this balance.
​
version
integer
Version number for optimistic concurrency control.
​
track_fund_lineage
boolean
Whether fund lineage tracking is enabled.
​
allocation_strategy
string
The allocation strategy for fund lineage (FIFO, LIFO, or PROPORTIONAL).
​
created_at
string
ISO 8601 timestamp when the balance was created.
​
inflight_expires_at
string
ISO 8601 timestamp when current inflight transactions expire.
​
meta_data
object
Custom metadata attached to the balance.
​
identity
object
The full identity object. Only included when include=identity is specified.
​
ledger
object
The full ledger object. Only included when include=ledger is specified.

​
Examples

curl https://api.blnk.io/balances/bal_123abc \
  -H "Authorization: Bearer YOUR_API_KEY"
Response Example
{
  "balance_id": "bal_123abc",
  "ledger_id": "ldg_456def",
  "identity_id": "usr_789ghi",
  "currency": "USD",
  "balance": "50000",
  "credit_balance": "100000",
  "debit_balance": "50000",
  "inflight_balance": "0",
  "inflight_credit_balance": "0",
  "inflight_debit_balance": "0",
  "currency_multiplier": 100,
  "version": 42,
  "track_fund_lineage": false,
  "allocation_strategy": "FIFO",
  "created_at": "2024-01-15T10:30:00Z",
  "inflight_expires_at": "2024-01-15T11:00:00Z",
  "meta_data": {
    "account_type": "checking"
  }
}

​
Understanding Balance States

​
Regular Balance

The net balance representing available funds: 
balance = credit_balance - debit_balance

​
Inflight Balance

Funds locked in pending transactions:
  • Inflight transactions are held temporarily until committed or voided
  • Useful for authorization holds, escrow, and multi-step transactions
  • Expires based on inflight_expires_at timestamp

​
Queued Balance

Funds in scheduled or queued transactions:
  • Only visible when with_queued=true
  • Represents future transactions not yet processed
  • Useful for forecasting and liquidity planning

​
Version Control

The version field enables optimistic concurrency control:
  • Increments with each balance update
  • Prevents race conditions in high-throughput scenarios
  • Ensures data consistency across distributed systems

Build docs developers (and LLMs) love

Get started for freeTalk to us