---
updatedAt: 2026-10-16T08:11:00.482Z
---

Fetch the complete documentation index at: https://docs.avvio.xyz/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.

# Get balance history

`GET https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/balance/history`

Why the balance is what it is.

Every movement, in the order it settled, with the running balance after
each. `balanceAfter` is published only when the running total reconciles
with `GET /balance`; otherwise a `note` says so and the entries stand
alone.

Entries are ordered by settlement time: a deposit by when it completed,
not when it was first seen. A settlement we record late (a deposit whose
completion reaches us after its own settlement time) is dated when it
settled, so it can land behind a cursor you already hold and not be
re-delivered. This view is for reading the balance's story. For exact
incremental reconciliation, page `GET /balance_transactions`, whose `id`
is assigned when a row is written and never lands behind one you have
seen.

Limited to 60 requests per minute per credential, below the read budget,
because each call replays your whole history. A high-frequency poller
belongs on `GET /balance_transactions`.

What adds an entry: a deposit to your funding account once it has
completed (never while pending), a sandbox top-up, and a payout drawn
from the prefunded balance (`DEBITED`). A debited payout that fails or is
canceled with the money coming back keeps its original debit and gains a
separate `reversal` entry (`RETURNED` or `CANCELED`); there is no
zero-delta row. One rejected by compliance stays debited.

What adds nothing: a payout you fund from your own wallet (one that
returns funding instructions, or `requiresFunding` in sandbox) never
touched the balance, including when you cancel it before funding. Nor
do movements on a payment network whose balance this record does not
track. When those leave the running total short of `GET /balance`,
`balanceAfter` is withheld under a `note`.

The whole history is read on every call, so `hasMore` is exact. An
organization with more than 100,000 orders is more than this view can
replay and gets `413 HISTORY_TOO_LARGE`; page `GET /balance_transactions`
instead, which has no such ceiling.

## Parameters

- `orgId` (path, required) — The opaque organization id issued to you, normally CUID-shaped (for example `cmsx…`). It is not an `org_`-prefixed alias. Pass it unchanged in every organization-scoped path.
- `limit` (query) — Maximum entries to return, from 1 to 500. Defaults to 100. Out-of-range values are clamped, not refused.
- `cursor` (query) — The `nextCursor` from your last page: entries after that one. Entries are append-only, so carrying it gives you what settled since — including a reversal appended days after the debit it reverses. A settlement recorded after its own settlement time is the exception (see above); `GET /balance_transactions` has none. Opaque; do not build one. Send `cursor` or `since`, not both.
- `since` (query) — Deprecated: use `cursor`. Entries strictly after this time. Two entries can share a millisecond, and paging on the last one's time skips the rest of that millisecond; `cursor` cannot.

## Example

```bash
curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/balance/history" \
  -H "x-api-key: $AVVIO_API_KEY"
```

## Responses

- `200` — Movements, in settlement order.
- `400` — `VALIDATION_ERROR` — `cursor` and `since` sent together, a cursor that is not one we issued, or a malformed `since`.
- `401` — The key was refused. Nothing ran. - `UNAUTHORIZED`: missing, invalid or revoked, or a key on a route that does not accept one. - `KEY_EXPIRED`: the key passed the expiry it was issued with. Issue a new one; an expired key cannot be rotated. - `KEY_IP_NOT_ALLOWED`: the key is pinned to source addresses and this request came from another.
- `403` — A valid key that may not make this call. Nothing ran. - `FORBIDDEN`: the key belongs to a different organization. - `ACCOUNT_BLOCKED`: API access for your organization is suspended, and every key is refused until we lift it. Contact support.
- `413` — `HISTORY_TOO_LARGE` — this organization has more orders than this view replays. Page `GET /balance_transactions`.
- `429` — Too many requests. The default ceiling is **100 requests per minute per API credential** on a 60-second window. High-volume payout and reconciliation routes declare a 600/minute override, and batch submission a 30/minute ceiling. A separate 2,000/minute per-source-IP abuse ceiling always applies. Obey `Retry-After`; it is in seconds and is authoritative. A 429 means the request was refused before the handler ran. Retry reads normally; retry an idempotent mutation with its same `Idempotency-Key`.

Machine contract: [partner-payouts.openapi.yaml](/partner-payouts.openapi.yaml), operation `getBalanceHistory`.