---
updatedAt: 2026-09-30T15:54:20.000Z
---

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.

# Batch payouts

Pay up to 1,000 people in one request, checked line by line before any money moves.

A batch carries a payroll file or a marketplace disbursement run as one
request. Each line is a `POST /payouts` body, so anything you can send alone
you can send in a batch.

## How it works

1. **Submit** the run with your own `externalReferenceId`, the id of the
   payroll file or cycle. The answer is `202`: received, not paid.
2. **Validate.** Every line is checked first, without pricing or debiting
   anything.
3. **Confirm or cancel.** A clean run with `autoCommit: true` goes straight to
   creation. A run with any invalid line, or with `autoCommit: false`, waits in
   `awaiting_confirmation` for you.
4. **Create.** The valid lines become ordinary payouts, with the same statuses,
   webhooks and bank returns as a payout sent alone.
5. **Reconcile** each created line through `GET .../batches/{batchId}/items`
   and the event feed.

## Coverage

A batch line can pay any corridor a single payout can. See
[Countries and currencies](/coverage/countries/) for the list, and read
`GET /recipients/{orgId}/corridors` for what your organization is routed to.

## Enablement and limits

Batches are on by default, bounded by the same caps, holds and approvals as a
single payout. If your organization has them turned off, submit and confirm
answer `403 MASS_PAYOUTS_DISABLED`; cancel and reads keep working. Test mode
inherits the live setting.

| Route                               | Limit           |
| ----------------------------------- | --------------- |
| `POST .../payouts/batches`          | 30 per minute   |
| `GET .../batches`, `GET .../batches/{batchId}`, `GET .../batches/{batchId}/items` | 600 per minute each |
| Lines per batch                     | 1 to 1,000      |

Split a bigger payroll into several batches, each with its own
`Idempotency-Key` and `externalReferenceId`. Rate limits are covered on
[Environments & sandbox](/environments/#rate-limits).

## Key features

### A run id that stops double runs

`externalReferenceId` is unique per organization, permanently. A job that
loses its `Idempotency-Key` and re-runs the file under a fresh one gets
`409 PAYOUT_BATCH_DUPLICATE_REFERENCE`, and nothing is submitted.

### One approval for the whole run

When your organization requires approval on API payouts, `autoCommit` is forced
off and the first confirm opens one approval covering every line. Once
approvers reach quorum, the run is released within a minute.

### Lines you can export

`GET .../batches/{batchId}/items?format=csv` returns the whole run with each
line's status, `payoutId` and first error. Error codes match a single
`POST /payouts`.

## Integration guides

- [Send a batch](/batch-payouts/): submit, review, confirm and reconcile a run.
- [Track status & failures](/status/#batch-payout-status): batch and payout statuses.
- [Reconcile your ledger](/reconciliation/): the event feed every created line reports to.