List balance transactions

Lists every movement on your balance, newest first.

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

GET/payments/organizations/{orgId}/balance_transactions

Open in explorer

curl

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"

Node

const res = await fetch(`${process.env.AVVIO_BASE_URL}/payments/organizations/${process.env.AVVIO_ORG_ID}/balance_transactions?cursor=48213&type=payout%2Cpayout_return&currency=USD`, {
  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_transactions",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
    },
    params={
        "cursor": "48213",
        "type": "payout,payout_return",
        "currency": "USD"
    },
)
print(res.status_code, res.json())

Try it

200OKResponse status200 OK400 Bad Request401 Unauthorized403 Forbidden429 Too Many Requests

{
  "data": [
    {
      "id": "48213",
      "type": "payout",
      "amount": "-100.00",
      "fee": "0.50",
      "net": "-99.50",
      "currency": "USD",
      "balanceAfter": "9900.00",
      "orderId": "sbx_pay_7c1c0f2e-6d9b-4a3e-9d1a-2f4b8c9e0a11",
      "batchId": null,
      "reference": "payroll-2026-09",
      "endUserId": "emp_412",
      "reason": null,
      "description": null,
      "createdAt": "2026-09-01T10:00:00.000Z"
    },
    {
      "id": "48212",
      "type": "funding",
      "amount": "10000.00",
      "fee": null,
      "currency": "USD",
      "balanceAfter": "10000.00",
      "orderId": null,
      "batchId": null,
      "reference": null,
      "endUserId": null,
      "reason": null,
      "description": null,
      "createdAt": "2026-09-01T09:00:00.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "48212"
}

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

• cursorstringOptional

  The nextCursor from your last page. Rows strictly older than it.

• limitintegerOptionalDefaults to 100

  Rows per page, from 1 to 100. Defaults to 100.

• typestringOptional

  Comma-separated. Any other value is a 400.

• orderIdstringOptional

  Everything that moved for one payout.

• currencystringOptional
• createdAfterstring<date-time>Optional

  Inclusive. ISO-8601 with a timezone.

• createdBeforestring<date-time>Optional

  Inclusive. ISO-8601 with a timezone.

Behavior

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.

Responses

200Rows, newest first. Served on every environment; before the historical rows are loaded on yours this is an empty page, not an error.

Body

• dataarray of objectRequired
  Show 15 properties

  • idstringRequired

    Monotonic, and the cursor. A string because it can exceed 2^53.

  • typestringRequired
    Allowed values:fundingpayoutpayout_returnhold

    Show 2 more values

    hold_releaseadjustment
  • amountstringRequired
  • feestring | nullRequired

    The fee portion of amount, same currency. Null when not known, which is different from zero.

  • netstringOptional

    What reached the corridor, the amount less the fee, carrying the amount's sign. Absent when fee is null.

  • currencystringRequired
  • balanceAfterstringRequired

    available after this row.

  • orderIdstring | nullOptional

    The payout this row belongs to, when it belongs to one. The same id GET /orders/{payoutId} takes.

  • snapshotIdstring | nullOptional

    The quote snapshot that sized this row. A hold is placed before the network has answered, so it has no orderId; its hold_release and the payout that converts it carry the same snapshotId, which is how you join a hold to its payout. Null on rows no snapshot sized (funding, adjustment).

  • batchIdstring | nullOptional
  • referencestring | nullOptional

    Your reference on the payout.

  • endUserIdstring | nullOptional
  • reasonstring | nullOptional

    Why, for returns, releases and adjustments, e.g. bank_return, canceled, quote_expired, stale_hold_released, operator.

  • descriptionstring | nullOptional
  • createdAtstring<date-time>Required
• hasMorebooleanRequired
• nextCursorstring | nullRequired

  Feed back as cursor. Null on the last page.

Errors

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

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 listBalanceTransactions

Try it: List balance transactions

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

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

cursor queryOptional

limit queryOptional

type queryOptional

orderId queryOptional

currency queryOptional

createdAfter queryOptional

createdBefore queryOptional

Send request