List batch items

Lists every line of a run, in submitted order, with the instruction you sent echoed back verbatim.

GET

GET/payments/organizations/{orgId}/payouts/batches/{batchId}/items

curl -s "$AVVIO_BASE_URL/payments/organizations/$AVVIO_ORG_ID/payouts/batches/$batchId/items?status=received&format=csv" \
  -H "x-api-key: $AVVIO_API_KEY"

const batchId = '<batchId>';

const res = await fetch(`${process.env.AVVIO_BASE_URL}/payments/organizations/${process.env.AVVIO_ORG_ID}/payouts/batches/${batchId}/items?status=received&format=csv`, {
  headers: {
    'x-api-key': process.env.AVVIO_API_KEY,
  },
});
console.log(res.status, await res.json());

import os
import requests

batchId = "<batchId>"

res = requests.get(
    f"{os.environ['AVVIO_BASE_URL']}/payments/organizations/{os.environ['AVVIO_ORG_ID']}/payouts/batches/{batchId}/items",
    headers={
        "x-api-key": os.environ["AVVIO_API_KEY"],
    },
    params={
        "status": "received",
        "format": "csv"
    },
)
print(res.status_code, res.json())

200OK

{
  "data": [
    {
      "index": 0,
      "status": "created",
      "instruction": {
        "amount": "200.00",
        "destinationAccountId": "sbx_acct_MXN_4471_ae66cbc5",
        "amountLeg": "source"
      },
      "instructionScrubbedAt": null,
      "payoutId": "sbx_pay_7c1c0f2e-6d9b-4a3e-9d1a-2f4b8c9e0a11"
    }
  ],
  "hasMore": true,
  "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": "BATCH_NOT_FOUND",
  "status": 404,
  "detail": "No payout batch cmf3k2xg00009q8b7v0w2x4yz belongs to this organization.",
  "requestId": "req-9na",
  "message": "No payout batch cmf3k2xg00009q8b7v0w2x4yz belongs to this organization.",
  "statusCode": 404
}

{
  "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
}

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.
batchIdstringRequired
From the 202 that accepted the run, or the batch list.

Query parameters

statusstringOptional
One item status to filter by.
Allowed values:receivedinvalidvalidatedcreating
Show 4 more values
createdcreate_failedcanceledrequires_review
limitintegerOptionalDefaults to 100
Page size, 1-1000. Defaults to 100.
cursorstringOptional
The nextCursor from your previous page, which is the last line index you saw. Not a whole number is a 400.
formatstringOptional
csv for the whole run as a file. JSON otherwise.
Allowed values:csv

Behavior

Join errors to your own file by content, not by counting rows. ?status=invalid is the review screen after awaiting_confirmation; ?status=created joins the run to the payout ledger; ?status=requires_review are lines whose outcome could not be established and were not retried.

?format=csv returns the run as a CSV file instead of a JSON page, honouring status and ignoring limit and cursor. Columns: index,status,payoutId,amount,amountLeg,destinationAccountId,reference,errorCode,errorMessage (the first error per line).

Responses

200One page of lines, or the CSV file when format=csv.

Body

dataarray of objectRequired
Show 6 properties
- indexintegerRequired
  Zero-based position in the items array you submitted.
- statusstringRequired
  One line's outcome at the creation level. invalid and create_failed are terminal refusals with errors attached and no payout behind them. Correct and resubmit in a new batch. requires_review is a line whose outcome could not be established (a process or network failure mid-flight). It is never retried automatically, because retrying an unknown outcome is how a crash becomes a double payment. Contact support with the batch id.
  Allowed values:receivedinvalidvalidatedcreating
  Show 4 more values
  createdcreate_failedcanceledrequires_review
- instructionobject | nullRequired
  The line you submitted, echoed back verbatim. Null once the echo has been scrubbed, 90 days after the batch completed; see instructionScrubbedAt.
  Show 8 properties
  - amountstringRequired
    How much, as a decimal string. What you send by default; what the recipient receives, in their currency, when amountLeg is destination.
  - destinationAccountIdstringRequired
    The recipient's method.destinationAccountId from the registration response (the account that call registered), or the one you stored for it.
  - amountLegstringOptionalDefaults to "source"
    Which side of the payout amount describes.
    More
    source takes every fee out of what you sent, so the recipient receives less than the figure you named.
    
    destination pays them that figure exactly, in their currency, and adds the fees to your debit instead. Naming 3400 MXN on a live corridor debited 201.879397 USDC and paid out 3400.00.
    
    source_net keeps the figure in your currency but means it the same way: "send them $200 worth". We convert at the market rate published by GET /rates and lock that destination, so the fees land on your debit. Naming 200 USD on a live corridor paid out 3426.81 MXN and debited 203.447236: the fees, plus the difference between the market rate we quoted you and the rate the network executed at.
    
    The two locking modes need capabilities.exactOutput on the corridors call; elsewhere they are refused with EXACT_OUTPUT_UNSUPPORTED rather than quietly pricing the other side.
    Allowed values:sourcedestinationsource_net
  - expectDestinationstringOptional
    What you told the payer they would receive. Omit it and you send at whatever the market did between quoting and sending.
  - maxDriftBpsintegerOptionalDefaults to 200
    Tolerated drift in basis points. Defaults to 200 (2%). Only read when expectDestination is set; ignored otherwise.
  - referencestringOptional
    Your payment reference. Echoed back and searchable.
  - purposeOfPaymentstringOptional
    Corridor-defined payment purpose, from GET /payment-reasons. Required for payouts to INR, GHS, CNY and BRL; validated against the catalog whenever you send it; never defaulted.
  - endUserobjectOptional
    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.
- instructionScrubbedAtstring<date-time> | nullOptional
  When the echoed instruction was removed under the retention policy.
- errorsarray of objectOptional
  Present on invalid and create_failed lines.
  Show 2 properties
  - codestringRequired
  - messagestringRequired
- payoutIdstringOptional
  Present once created, and the payout to track from here on.
hasMorebooleanRequired
nextCursorstring | nullRequired
Pass as cursor to continue. 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.
404
BATCH_NOT_FOUND: no such batch in this organization.
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 · Payout batches · operation listPayoutBatchItems

Try it: List batch items

GET https://api.avvio.xyz/business/api/v1/payments/organizations/{orgId}/payouts/batches/{batchId}/items

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

batchId pathRequired

status queryOptional

limit queryOptional

cursor queryOptional

format queryOptional

Was this page helpful?