Balance & ledger

Read your available balance and every entry behind it.

Balance & ledger

Reconcile payouts, fees and refunds without exporting CSVs: the balance endpoints expose the same ledger your wallet is built on.

Endpoints

Method Path Scope Purpose
GET /v1/balance balance:read Available, pending and instantly available amounts per currency.
GET /v1/balance/transactions balance:read Ledger entries, newest first.
GET /v1/balance/transactions/{id} balance:read Retrieve one entry.

Payouts themselves stay dashboard-only — no API key can move money out of a balance.

Balance

curl https://api.southbill.com/v1/balance \
  -H "Authorization: Bearer sk_live_..."

{
  "object": "balance",
  "available": [{ "amount": 128400, "currency": "eur" }],
  "pending": [{ "amount": 24990, "currency": "eur" }],
  "instant_available": [{ "amount": 90000, "currency": "eur" }]
}

Each list holds one entry per currency; amounts are integers in the smallest currency unit.

Ledger entries

curl "https://api.southbill.com/v1/balance/transactions?type=charge&created_gte=1767225600&limit=50" \
  -H "Authorization: Bearer sk_live_..."

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "id": "txn_…",
      "object": "balance_transaction",
      "type": "charge",
      "source": "ch_…",
      "amount": 4990,
      "fee": 174,
      "net": 4816,
      "currency": "eur",
      "status": "available",
      "available_on": 1767398400,
      "created": 1767225600
    }
  ]
}

Filters: type, currency, created_gte, created_lte, plus limit (1–100, default 25) and starting_after cursor pagination.

Reading the numbers

  • amount is gross, fee is what was deducted, net is what hits the balance — reconcile on net.
  • source points at the object that created the entry (ch_…, re_…, po_…), so you can join entries back to payments, refunds and payouts.
  • available_on is when a pending entry becomes withdrawable.
  • exchange_rate is set on cross-currency entries.
  • Refunds and fee reversals appear as their own negative entries — a refunded payment keeps its original charge entry.