Get balance history

Why the balance is what it is.

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

GET/payments/organizations/{orgId}/balance/history

Open in explorer

curl

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

Node

const res = await fetch(`${process.env.AVVIO_BASE_URL}/payments/organizations/${process.env.AVVIO_ORG_ID}/balance/history`, {
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
  },
});
console.log(res.status, await res.json());

Python

import os
import requests

res = requests.get(
    f"{os.environ['AVVIO_BASE_URL']}/payments/organizations/{os.environ['AVVIO_ORG_ID']}/balance/history",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
    },
)
print(res.status_code, res.json())

Try it

200OKResponse status200 OK400 Bad Request401 Unauthorized403 Forbidden413 429 Too Many Requests

{
  "hasMore": false,
  "nextCursor": "eyJhdCI6IjIwMjYtMDgtMjBUMTQ6MDM6MTEuMDAwWiIsImlkIjoiMDFKN044UTJZUTFDNEc5TTJYNlIifQ",
  "nextSince": "2026-08-20T14:03:11.000Z",
  "entries": [
    {
      "id": "sbx_fund_3d6f9a2c-1b4e-4c7d-8a5f-0e2b9c4d7a61",
      "type": "funding",
      "status": "COMPLETED",
      "currency": "USD",
      "amount": "10000.00",
      "balanceAfter": "10000.00",
      "at": "2026-08-20T13:40:00.000Z"
    },
    {
      "id": "sbx_pay_7c1c0f2e-6d9b-4a3e-9d1a-2f4b8c9e0a11",
      "type": "payout",
      "status": "DEBITED",
      "currency": "USD",
      "amount": "-200.00",
      "balanceAfter": "9800.00",
      "reference": "ZZ-WAGE-1",
      "at": "2026-08-20T14:03:11.000Z"
    }
  ]
}

Path parameters

• orgIdstringRequired

  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.

Query parameters

• limitintegerOptionalDefaults to 100

  Maximum entries to return, from 1 to 500. Defaults to 100. Out-of-range values are clamped, not refused.

• cursorstringOptional

  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.

• sincestring<date-time>Optional

  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.

Behavior

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.

Responses

200Movements, in settlement order.

Body

• hasMorebooleanOptional
• nextCursorstring | nullOptional

  Feed back as cursor. It is NOT null when you are caught up: an empty page returns the position you sent — terminate on hasMore: false. Null only when the history is empty and no cursor or since was sent.

• nextSincestring<date-time> | nullOptional

  Deprecated: use nextCursor. The last entry's time; paging on it skips entries sharing that millisecond. Feed it back as since. It is not null when you are caught up: an empty page returns the since you sent, so terminate on hasMore: false. A loop waiting for null never ends. Null only when the history is empty and no since was sent.

• entriesarray of objectOptional
  Show 8 properties

  • idstringOptional

    The payout or deposit id; a reversal is <payoutId>:reversal.

  • typestringOptional

    reversal is a debited payout's money coming back, returned by the bank (RETURNED) or canceled (CANCELED): a separate appended entry, never a rewrite of the original debit.

    Allowed values:fundingpayoutreversal
  • statusstringOptional

    What this entry records, frozen when it was written, and not the payout's current status, which would make a historical row mutate under a reconciler that had already read it. DEBITED money left, RETURNED money came back from a failed payout, CANCELED money came back from a canceled one, COMPLETED funding landed.

    Allowed values:COMPLETEDDEBITEDRETURNEDCANCELED
  • currencystringOptional
  • amountstringOptional
  • balanceAfterstringOptional

    Present only when the ledger reconciles with GET /balance.

  • referencestringOptional

    Your payout reference. Absent when there was none (a sandbox top-up has none).

  • atstring<date-time>Optional

Errors

• 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.

Error body · Error

• typestringRequired

  Stable machine-readable code.

• detailstringRequired

  What went wrong, in a sentence. Always a string, so detail.toLowerCase() is safe.

  More

  This is the field to read on BAD_REQUEST and PROVIDER_REJECTED, where the type alone does not name the condition.

• messagestringRequired

  The same text as detail, kept for integrations written before detail existed. Read detail.

• resolutionstringOptional

  What to do about it, when there is a specific answer. It is not on every error (it is absent on BAD_REQUEST, NOT_FOUND, PAYOUT_NOT_CANCELABLE and DESTINATION_ACCOUNT_NOT_FOUND), so treat it as optional and fall back to detail.

• statusintegerRequired

  HTTP status, repeated in the body.

• statusCodeintegerRequired

  The same value as status, kept for integrations written before status existed. Read status.

• requestIdstringRequired

  Quote this to support and we can find the exact request. Also sent as the x-request-id response header, which is the only place it appears on a successful response. Success bodies do not carry it. Send your own x-request-id on the request and we use it, so your trace and ours share one identifier; otherwise we mint one.

• errorsarray of stringOptional

  Present on VALIDATION_ERROR; names each field that failed.

• originalIdempotencyKeystringOptional

  On DUPLICATE_REQUEST_DETECTED only. Send the request again with this to receive the original payout instead of making a second one. Without it there is no way to recover except by risking a double payment.

• originalPayoutIdstringOptional

  On DUPLICATE_REQUEST_DETECTED only. The payout the first request created.

• originalBatchIdstringOptional

  On a batch DUPLICATE_REQUEST_DETECTED. The run the first request created.

• originalRequestIdstringOptional

  On a 409 PAYOUT_OUTCOME_UNKNOWN replay. The requestId of the call whose outcome is unknown; quote it to support.

• existingRecipientIdstringOptional

  On BANK_ACCOUNT_ALREADY_LINKED. The recipient in your organization that already holds this account.

• existingMethodIdstringOptional

  On BANK_ACCOUNT_ALREADY_LINKED. The payment method on that recipient.

Branch on type, never on the status or the message. Every error type is listed with what to do about it.

Avvio Partner Payouts · Funding & balance · operation getBalanceHistory

Try it: Get balance history

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

API key Required

Test keys only. Sent as x-api-key through this site's proxy to the Avvio API, never saved, and cleared when you close this dialog.

orgId pathRequired

limit queryOptional

cursor queryOptional

since queryOptional

Send request