# 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

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

```json
{
  "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

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

```json
{
  "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.