List payouts

Recent payouts.

GET

GET/payments/organizations/{orgId}/orders

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

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

import os
import requests

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

200OK

{
  "data": [
    {
      "payoutId": "sbx_pay_7c1c0f2e-6d9b-4a3e-9d1a-2f4b8c9e0a11",
      "status": "processing",
      "stage": "settling",
      "sourceAmount": {
        "currency": "USD",
        "amount": "200.00"
      },
      "destinationAmount": {
        "currency": "MXN",
        "amount": "3384.65"
      },
      "destinationAccountId": "sbx_acct_MXN_4471_ae66cbc5",
      "fee": {
        "currency": "USD",
        "amount": "1.02"
      },
      "rate": "16.923250",
      "reference": "ZZ-WAGE-1",
      "endUser": {
        "id": "customer_42",
        "name": "Northwind Payroll LLC",
        "email": "[email protected]"
      },
      "createdAt": "2026-08-20T14:03:11.000Z",
      "updatedAt": "2026-08-20T14:03:12.480Z",
      "completedAt": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

{
  "type": "VALIDATION_ERROR",
  "status": 400,
  "detail": "limit must be a whole number between 1 and 100.",
  "resolution": "Correct the fields listed in `errors` and retry.",
  "errors": [
    "limit: \"500\" is above the maximum of 100"
  ],
  "requestId": "req-9ul",
  "message": "limit must be a whole number between 1 and 100.",
  "statusCode": 400
}

{
  "type": "UNAUTHORIZED",
  "status": 401,
  "detail": "Invalid API key",
  "resolution": "Check the API key was copied whole and has not been revoked.",
  "requestId": "req-9bz",
  "message": "Invalid API key",
  "statusCode": 401
}

{
  "type": "FORBIDDEN",
  "status": 403,
  "detail": "This API key cannot access that organization",
  "resolution": "This key is scoped to a different organization.",
  "requestId": "req-9d0",
  "message": "This API key cannot access that organization",
  "statusCode": 403
}

{
  "type": "RATE_LIMITED",
  "status": 429,
  "detail": "ThrottlerException: Too Many Requests",
  "resolution": "Back off and retry after the Retry-After interval.",
  "requestId": "req-9e1",
  "message": "ThrottlerException: Too Many Requests",
  "statusCode": 429
}

{
  "type": "ORDERS_TEMPORARILY_UNAVAILABLE",
  "status": 503,
  "detail": "We could not read the full payout list, so this page would have been incomplete and we will not report it as complete. Retry shortly.",
  "requestId": "req-ad1",
  "message": "We could not read the full payout list, so this page would have been incomplete and we will not report it as complete. Retry shortly.",
  "statusCode": 503
}

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

updatedSincestring<date-time>Optional
Use this as the change feed. It returns payouts whose state changed at or after this time, oldest-changed first.
More
Ordinary listing is newest-first by creation, which by construction can never tell you that an old payout changed, and completed → failed on a bank return, days later, is exactly the change a ledger cannot afford to miss. Page forward with nextCursor, carry the last updatedAt you saw as your watermark, and you will observe every revision without re-reading your whole history.

At-least-once, not exactly-once: updatedSince is inclusive, so resuming from your watermark re-reads the row at that instant. Dedupe on payoutId + updatedAt.
statusarray of stringOptional
One comma-separated list of canonical statuses, e.g. processing,completed.
endUserIdstringOptional
Your id for the person the payout belongs to.
referencestringOptional
Your payment reference, matched exactly.
createdAfterstring<date-time>Optional
Return payouts created at or after this RFC 3339 timestamp.
createdBeforestring<date-time>Optional
Return payouts created at or before this RFC 3339 timestamp.
limitintegerOptionalDefaults to 50
Maximum payouts to return, from 1 to 100. Defaults to 50. Outside the range is a 400, not clamped.
cursorstringOptional
The nextCursor from the previous page, passed back verbatim. It is opaque; do not parse or construct one.

Responses

200A page of payouts. Newest-created first, or oldest-changed first when updatedSince is set.

Body

dataarray of objectRequired
Show 17 properties
- payoutIdstringOptional
- statusstringOptional
  A payout moves only along these transitions:
  More
  pending -> processing | completed | failed | canceled processing -> completed | failed completed -> failed (returned by the recipient's bank)
  
  pending: accepted, reserved, not sent. The only cancelable state.
  
  processing: handed to the payment network. Committed.
  
  completed: the recipient was paid. Not absolutely final.
  
  failed: not paid, or paid and then returned. Branch on failureCode.
  
  canceled: you ended it before it was sent. It is not a failure, so it carries no failureCode; fundsReturned is true because the money never left.
  
  completed can still become failed. A receiving bank can return a payment days after settlement, giving failureCode: returned_by_bank and fundsReturned: true. Do not write a ledger that treats completed as immutable, and keep processing webhooks for a payout after it completes.
  Allowed values:pendingprocessingcompletedfailed
  Show 1 more value
  canceled
- stagestringOptional
  Informational sub-state on a slow payout, so your support team can answer "where is it?". Non-authoritative: never branch integration behavior on it, and treat an unrecognized value as the status alone.
  Allowed values:awaiting_detailsunder_reviewsettling
- failureCodestringOptional
  New codes may be added; treat an unknown one as execution_failed.
  Allowed values:quote_expiredinsufficient_fundslimit_exceededaccount_invalid
  Show 6 more values
  account_cannot_receivecompliance_rejectedauthorization_not_completedreturned_by_bankexecution_failedunknown
- requiresFundingbooleanOptional
  Present and true when this payout is waiting on you to fund it from your own wallet. Absent on routings that settle on acceptance, so its presence is the signal.
- fundsReturnedbooleanOptional
  Whether the money is back in your balance. Separate from failureCode, because the same cause can go either way depending on how far the payment got.
- sourceAmountobject | nullOptional
  Always a decimal string, never a float and never base units. Floats lose cents at scale; base units mean every integrator re-derives the exponent.
  Show 2 properties
  - currencystringRequired
  - amountstringRequired
- destinationAmountobject | nullOptional
  Always a decimal string, never a float and never base units. Floats lose cents at scale; base units mean every integrator re-derives the exponent.
  Show 2 properties
  - currencystringRequired
  - amountstringRequired
- destinationAccountIdstring | nullOptional
- feeobject | nullOptional
  The fee, already inside sourceAmount, deducted from the send not added on top, so destinationAmount = sourceAmount x rate still holds. The same value the event data and the payout row on /balance_transactions report. Null when the rail has not disclosed it, which is "not known", not zero.
  Show 2 properties
  - currencystringRequired
  - amountstringRequired
- ratestring | nullOptional
  The effective rate: destinationAmount / sourceAmount, derived from this payout's own amounts with the fee inside, so destinationAmount = sourceAmount x rate always holds. Lower than the indicative mid-rate GET /rates showed for the same conversion by exactly the fee share; that is not the rate moving. Compare it to PreviewQuote.rate only after netting the fee. Always six decimal places, rounded half-up ("16.923250"). Null until the amounts are known.
- referencestring | nullOptional
- endUserobject | nullOptional
  Your own customer this payout is sent for: the party sending through your platform, never the recipient. In payroll the employer is the end user and the worker is the recipient; omit the object when you are the sender yourself. Attribution and the per-end-user daily cap key on id; it is not forwarded to the payment network and does not change the sender of record, which stays your organization. Echoed on the payout and in every webhook, so a support question is answerable without your own id map.
  Show 3 properties
  - idstringOptional
    Your stable identifier for the sending customer (not the recipient).
  - namestringOptional
    Person's display or legal name.
  - emailstring<email>Optional
    Person's email address in standard email format.
- createdAtstring<date-time> | nullOptional
- updatedAtstring<date-time> | nullOptional
  When this payout last changed. Carry the highest value you have seen as your updatedSince watermark. Without it in the payload the change feed cannot be paged.
- completedAtstring<date-time> | nullOptional
- expectedSettlementAtstring<date-time>Optional
  When the funds are expected to be available to the recipient, where the routing states a settlement timeline. Present only when known; an estimate, not a promise.
hasMorebooleanRequired
nextCursorstring | nullOptional

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.
503
ORDERS_TEMPORARILY_UNAVAILABLE: we could not read the full list, so we refuse to hand you a page that would look complete. Retry shortly; nothing is wrong with your request.

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 · Payouts · operation listPayouts

Try it: List payouts

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

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

updatedSince queryOptional

status queryOptional

endUserId queryOptional

reference queryOptional

createdAfter queryOptional

createdBefore queryOptional

limit queryOptional

cursor queryOptional

Was this page helpful?