---
updatedAt: 2026-09-30T17:50:34.235Z
---

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.

# List balance transactions

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

Lists every movement on your balance, newest first. Reconcile your
balance by pulling this list. It has one row per change to what you can spend: funding in, payouts out, returns, holds and their
release, and operator adjustments. Rows are append-only and each carries
`balanceAfter`, so your ledger can be checked row by row rather than
against a single number.

`id` is the cursor: page with `cursor=<last id>` and rows come back
strictly older. Idempotent by `id`: a resumed run that re-reads a row
is harmless.

`net` is what reached the corridor: the amount less the fee, carrying
the amount's sign. It is absent when the fee is not known.

Holds appear here too. If `available` on `GET /balance` is lower than
the movements explain, the difference is a hold and it is listed here.

## 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.
- `cursor` (query) — The `nextCursor` from your last page. Rows strictly older than it.
- `limit` (query) — Rows per page, from 1 to 100. Defaults to 100.
- `type` (query) — Comma-separated. Any other value is a 400.
- `orderId` (query) — Everything that moved for one payout.
- `currency` (query)
- `createdAfter` (query) — Inclusive. ISO-8601 with a timezone.
- `createdBefore` (query) — Inclusive. ISO-8601 with a timezone.

## Example

```bash
curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/balance_transactions?cursor=48213&type=payout%2Cpayout_return&currency=USD" \
  -H "x-api-key: $AVVIO_API_KEY"
```

## Responses

- `200` — Rows, newest first. Served on every environment; before the historical rows are loaded on yours this is an empty page, not an error.
- `400` — `VALIDATION_ERROR`: a query parameter was refused, and `errors` names it. A `limit` outside its range is refused, not clamped; a `cursor` we did not issue for this organization is refused (start from the first page); an unknown filter value or a parameter sent twice is refused.
- `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.
- `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 `listBalanceTransactions`.