> ## Documentation Index
> Fetch the complete documentation index at: https://docs.infinityapp.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Batches

> Every POST /payouts call creates a batch. Use it to track a set of payouts together, from creation to completion.

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

```bash theme={null}
curl "$BASE/batches/batch_fcb4cuwtd6fcbmwr" -H "Authorization: Bearer $INFINITY_KEY"
```

```json Response (abridged) theme={null}
{
  "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

```bash theme={null}
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`](https://docs.infinityapp.in/guides/payouts#cancel-a-payout-on-hold); 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.