# Batches

Source: https://tenergy.me/docs/batches
Last updated: 2026-09-25

`POST /v1/batches` orders for up to 100 receivers at once. For each receiver the platform activates the address if needed, tops up bandwidth if it is short, then delivers the resource, splitting large amounts into chunks.

## How a batch behaves

| Property | Behaviour |
|---|---|
| Response | `202 Accepted`: queued, nothing charged, nothing delivered yet |
| Result | `GET /v1/batches/{id}`, or the per-order [webhooks](https://tenergy.me/docs/webhooks) (`order.confirmed` carries `batch_id`) |
| Billing | Per receiver, at the price in force when that receiver runs; cap it with `max_price_sun` per item |
| Isolation | One receiver failing never affects the others; a failed activation or bandwidth step does not stop that receiver's resource order |
| Orders | Each receiver gets its own order id — what you inspect, reclaim and reconcile against |
| Idempotency | `client_batch_id`: same id + same body returns the original batch; same id + different body is `3010 idempotency_conflict` |
| Cancel | `POST /v1/batches/{id}/cancel` stops the not-yet-started part; receivers already picked up return `3002 order_not_cancellable` |
| Rate limit | Order creation (`POST /v1/orders`, `POST /v1/batches`) shares 30 rps |

## Request

`defaults` apply to every item; an item overrides any field.

```json title="POST /v1/batches"
{
  "client_batch_id": "acme-payout-2026-09-11-01",
  "defaults": { "resource": "energy", "tier": "1h", "amount": 65000, "activate": true, "bandwidth": true, "bandwidth_amount": 400 },
  "items": [
    { "receiver": "TQn9Y2khEsLJW1ChVWFMSMeRDow5KcbLSE" },
    { "receiver": "TXXxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "amount": 131000 },
    { "receiver": "TYYyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy", "bandwidth": false }
  ]
}
```

## Endpoints

| Method | Path | Purpose |
|---|---|---|
| `POST` | `/v1/batches` | Create a batch |
| `GET` | `/v1/batches` | List batches |
| `GET` | `/v1/batches/{batchId}` | Progress and per-receiver orders |
| `POST` | `/v1/batches/{batchId}/cancel` | Cancel the not-yet-started part |

Field-level schemas: [Batches — API reference](https://tenergy.me/docs/api/batches).