> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/settlement/batches.md).

# Batches

Batches group completed payments for settlement processing and reconciliation.

Use Batches when you need to see which payments were grouped together, review batch-level fee totals, or connect grouped payment activity to a settlement record.

For payment history and transaction-level search, use [Reporting](/reporting.md) first. For the settlement-level fee rollup, use [Settlements](/settlement/settlements.md). For payment-level settlement detail, use [Payment Settlement Detail](/settlement/payment-settlement-detail.md). For funded bank movement, use [Deposits](/settlement/deposits.md).

#### When to use Batches

Use Batches when you need to:

* Review which payments were grouped into a batch.
* See batch-level gross amount, fees, and net fundable amount.
* Validate that batch fee totals roll up to the settlement's `totalTransactionFees`.
* Filter batch activity by merchant, settlement, date range, status, or type.
* Connect batch activity to a settlement record.
* Reconcile a settlement back to the individual payments behind it.

#### How it works

When payments complete, Bead groups them into a batch for the settlement period. Each batch carries a `grossFundableAmount`, a `totalFees` amount representing the transaction fees withheld, and a `netFundableAmount`. When the settlement period closes, batches are rolled into a [Settlement](/settlement/settlements.md) record. The sum of `totalFees` across all batches equals the `totalTransactionFees` on the Settlement.

A typical batch reconciliation flow:

1. Start with a merchant, settlement ID, or date range.
2. Retrieve batch records using the relevant filters.
3. Review gross fundable amount, total fees, net fundable amount, and transaction count.
4. Use `paymentIds` to connect the batch back to individual payments.
5. Use `settlementId` to connect the batch to the parent settlement record.

#### Available endpoints

| Scope              | Path                                | Description                                                                                                     |
| ------------------ | ----------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Batch list         | GET /Batches                        | Returns batch records with filters for date range, status, type, merchant, settlement, pagination, and sorting. |
| Single batch       | GET /Batches/{id}                   | Returns one batch record by batch ID.                                                                           |
| Merchant batches   | GET /Batches/merchants/{merchantId} | Returns batch records for a specific merchant.                                                                  |
| Settlement batches | GET /Settlements/{id}/batches       | Returns batch records associated with a settlement.                                                             |

#### Query parameters

| Parameter     | Type             | Description                                               |
| ------------- | ---------------- | --------------------------------------------------------- |
| From          | date             | Start of the date range filter.                           |
| To            | date             | End of the date range filter.                             |
| Status        | string           | Filter by batch status. See Batch status.                 |
| Type          | string           | Filter by currency category: crypto, walletApps, or fiat. |
| MerchantIds   | array of strings | Filter by one or more merchant IDs.                       |
| SettlementIds | array of strings | Filter by one or more settlement IDs.                     |
| Page          | integer          | Page number. Defaults to 0.                               |
| PageSize      | integer          | Results per page. Defaults to 50, maximum 100.            |
| SortBy        | string           | Field to sort by.                                         |
| SortDirection | string           | Sort direction: asc or desc.                              |

#### Batch fields

| Field               | Type              | Description                                                                                        |
| ------------------- | ----------------- | -------------------------------------------------------------------------------------------------- |
| id                  | string            | Unique batch identifier.                                                                           |
| merchantId          | string            | Merchant associated with the batch.                                                                |
| status              | string            | Current batch status. See Batch status.                                                            |
| type                | string            | Batch currency category. See Batch type.                                                           |
| totalFees           | number or string  | Transaction fees withheld for this batch. Sums to `totalTransactionFees` on the parent Settlement. |
| grossFundableAmount | number or string  | Total payment volume in the batch before fees.                                                     |
| netFundableAmount   | number or string  | Net amount after fees.                                                                             |
| transactionCount    | integer or string | Number of payments included in the batch.                                                          |
| paymentIds          | array of strings  | Payment IDs included in the batch.                                                                 |
| batchPeriod         | date              | Date associated with the batch period.                                                             |
| settlementId        | string or null    | Settlement associated with the batch, when assigned.                                               |

#### Batch status

| Value  | Description                                         |
| ------ | --------------------------------------------------- |
| open   | Batch is open and accepting payments.               |
| closed | Batch has been closed and submitted for settlement. |
| hold   | Batch is on hold pending review.                    |

#### Batch type

| Value      | Description                         |
| ---------- | ----------------------------------- |
| crypto     | Batch contains crypto payments.     |
| walletApps | Batch contains wallet app payments. |
| fiat       | Batch contains fiat card payments.  |

#### Fee rollup

Batch fees roll up to the settlement level. For any settlement, the sum of `totalFees` across all associated batches equals the `totalTransactionFees` on the Settlement record.

Use this to cross-check settlement-level fee totals against batch-level detail. If there is a discrepancy, contact Bead support.

#### Typical integration flows

**Review batches for a merchant**

Goal: show batch activity for a merchant.

1. Retrieve batches filtered by `MerchantIds` and date range.
2. Display batch status, type, batch period, gross fundable amount, total fees, net fundable amount, and transaction count.
3. Allow the user to select a batch for payment-level detail.

**Reconcile a settlement to batches**

Goal: understand which batches are included in a settlement.

1. Use `GET /Settlements/{id}/batches` to retrieve batches for the settlement.
2. Review each batch's gross fundable amount, `totalFees`, net fundable amount, and transaction count.
3. Confirm that the sum of `totalFees` across all batches matches `totalTransactionFees` on the settlement.

**Reconcile a batch to payments**

Goal: connect a batch back to the payments in it.

1. Retrieve the batch record.
2. Use `paymentIds` to retrieve the underlying payments. See [Payment Settlement Detail](/settlement/payment-settlement-detail.md) to review settlement context for those payments.
3. Match batch totals to your internal ledger.

#### Next steps

* Use [Settlements](/settlement/settlements.md) for the period-level fee rollup, adjustments, and net fundable amount.
* Use [Residual Reporting](/settlement/residual-reporting.md) to understand how batch fees feed into monthly residual calculations.
* Use [Deposits](/settlement/deposits.md) to confirm funded bank movement tied to a settlement.
* Use [Payment Settlement Detail](/settlement/payment-settlement-detail.md) for payment-level settlement context and to trace payments through the settlement lifecycle.
* Use [Reporting](/reporting.md) when you need payment history before reviewing batches.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/settlement/batches.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.