Batches

A batch is the set of payouts created by one POST /payouts call, from 1 to 100. It carries the call’s name, description, reference and metadata, aggregates its payouts’ totals, and derives a status from theirs, so you can follow a payroll run or an invoice cycle as one unit. Batches are created only through POST /payouts; there’s no separate create endpoint.

The batch object

curl "$BASE/batches/batch_fcb4cuwtd6fcbmwr" -H "Authorization: Bearer $INFINITY_KEY"

Response (abridged)

{
  "id": "batch_fcb4cuwtd6fcbmwr",
  "number": "PB-2026-21",
  "name": "October invoices",
  "description": "Contractor invoices, October",
  "status": "partially_completed",
  "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
  "debit_currency": "usd",
  "total_debit": "1778.35",
  "total_fee": "20.00",
  "payee_count": 2,
  "payout_summary": {
    "total": 2, "pending": 0, "processing": 0, "paid": 1, "failed": 0, "returned": 0,
    "awaiting_payee": 0, "awaiting_funds": 0, "canceled": 0, "expired": 1
  },
  "payouts": [ { "id": "payout_4kz9xq7m2w8dn3ra", "status": "paid", "...": "…" }, { "id": "payout_9dq3m7xk2wr5hn8t", "status": "expired", "...": "…" } ],
  "reference": "run-2026-10",
  "metadata": {},
  "created_at": "2026-10-26T10:05:00Z",
  "updated_at": "2026-11-25T10:05:00Z"
}

Field	Meaning
`number`	Your account’s sequential batch number, as shown on the dashboard.
`name`	The name sent on creation, or `API batch` plus the UTC date and time.
`wallet_id`, `debit_currency`	The wallet that paid, and its currency.
`total_debit`, `total_fee`	Sums of the payouts’ `debit_amount` and `fee`.
`payout_summary`	The number of payouts in each status. Every count is always present.
`payouts`	The batch’s payouts, in the order they were requested.

Batch statuses

A batch’s status is derived from its payouts and recalculated whenever one of them changes, so it can move more than once and can move backwards: a batch that was processing returns to awaiting_payees when the only payout left is waiting for its payee.

Status	Meaning
`pending`	Payouts have been created and are being handed to the network.
`processing`	At least one payout is in transit.
`awaiting_payees`	At least one payout is on hold for its payee.
`awaiting_funds`	At least one payout is waiting for the wallet to be funded.
`completed`	Every payout was paid.
`partially_completed`	Every payout reached a final status, and some weren’t paid.
`failed`	Every payout reached a final status, and none was paid.
`canceled`	Every payout was canceled.

A returned payout counts as not delivered. A completed batch therefore becomes partially_completed, or failed, if one of its payouts is later returned.

List batches

curl "$BASE/batches?status=awaiting_funds&limit=20" -H "Authorization: Bearer $INFINITY_KEY"

GET /batches filters by status, created[gte] and created[lte], returns results newest first and pages with limit and starting_after. To list a batch’s payouts with filters, use GET /payouts?batch_id=batch_fcb4cuwtd6fcbmwr.

Canceling

Batches can’t be canceled as a whole. Cancel each payout that’s still on hold with POST /payouts/{id}/cancel; the batch’s status follows.

Events

A batch emits batch.created when it’s created, then an event each time its status changes: batch.processing, batch.awaiting_payees, batch.awaiting_funds, batch.completed, batch.partially_completed, batch.failed and batch.canceled. A single payout change often produces two events, such as payout.paid followed by batch.completed; they aren’t guaranteed to arrive in that order.

Get started

Concepts

Build reliably

The batch object

Batch statuses

List batches

Canceling

Events