# Batches

Batch records help integrators understand how completed payments are grouped for settlement processing and reconciliation.

Use Batches when you need to see which payments were grouped together, review batch-level amounts, or connect a group of payments to a settlement record.

Batches are returned through Bead APIs. They are not a settlement file, statement, or custom export.

#### When to use Batches

Use Batches when you need to:

* Review groups of payments prepared for settlement.
* See which payment IDs are included in a batch.
* Filter batch activity by merchant, settlement, date range, status, or type.
* Compare gross fundable amount, fees, and net fundable amount.
* Connect batch activity to settlement records.
* Reconcile a settlement back to the payments included in it.
* Support merchant or partner questions about how payments were grouped.

For payment history and transaction-level search, use Reporting APIs first. For payment-level settlement detail, use Payment Settlements. For merchant-level settlement batches, use Merchant Settlements. For funded movement tied to settlement, use Deposits.

#### How it works

A batch groups one or more payments for settlement processing.

A typical batch reconciliation flow is:

1. Start with a merchant, settlement, or date range.
2. Retrieve batch records using the relevant filters.
3. Review the batch status, type, batch period, and settlement identifier.
4. Use the payment IDs in the batch to reconcile individual payments.
5. Use the settlement identifier to connect the batch to settlement and deposit activity.

#### Available endpoints

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

#### Shared query parameters

The batch list, merchant batch, and settlement batch endpoints support filters that help narrow results for reconciliation and support workflows.

Common filters include:

* `From`
* `To`
* `Status`
* `Type`
* `MerchantIds`
* `SettlementIds`
* `Page`
* `PageSize`
* `SortBy`
* `SortDirection`

`From` and `To` use date values. `MerchantIds` and `SettlementIds` accept arrays of IDs. `Page` defaults to `0`, and `PageSize` defaults to `50` with a maximum of `100`.

Use merchant and date filters when reviewing activity for a known merchant and settlement period. Use settlement filters when reconciling a known settlement. Use status and type filters when reviewing settlement workflow or currency category.

#### Batch fields

A batch record can include:

| Field                 | Type             | Description                                                                          |
| --------------------- | ---------------- | ------------------------------------------------------------------------------------ |
| `id`                  | string           | Unique batch identifier.                                                             |
| `merchantId`          | string           | Merchant associated with the batch.                                                  |
| `status`              | string           | Current batch status. Expected values include `open`, `closed`, and `hold`.          |
| `type`                | string           | Batch currency category. Expected values include `crypto`, `walletApps`, and `fiat`. |
| `totalFees`           | number           | Total fees associated with the batch.                                                |
| `grossFundableAmount` | number           | Gross fundable amount before fees are applied.                                       |
| `netFundableAmount`   | number           | Net fundable amount after fees are applied.                                          |
| `transactionCount`    | integer          | Number of transactions 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

Batch status indicates the current state of the batch.

Supported status values include:

* `open`
* `closed`
* `hold`

Use the status field to filter batch records and display batch state in reconciliation or support workflows.

#### Batch type

Batch type identifies the currency category for the batch.

Supported type values include:

* `crypto`
* `walletApps`
* `fiat`

Use the type field when separating crypto, wallet app, and fiat settlement activity.

#### Relationship to Settlement

Batches are part of the broader Settlement model.

Use Batches when you need to understand which payments were grouped together. Use Settlement records to understand the broader settlement event. Use Payment Settlements when you need payment-level settlement detail. Use Deposits when you need to confirm funded movement tied to a settlement.

A common pattern is:

1. Use [Reporting](/reporting.md) APIs to find completed payments.
2. Use [Batches](/settlement/batches.md) to understand how those payments were grouped.
3. Use [Settlement](/settlement.md) APIs to connect the batch to a settlement record.
4. Use [Payment Settlements](/settlement/payment-settlements.md) for payment-level settlement detail.
5. Use [Deposits](/settlement/deposits.md) to confirm funded movement and deposit status.

#### Files, exports, and API reporting

Batch data is available through Bead APIs.

Most integrations should use the documented API responses for batch reconciliation. If a partner needs a custom export or file delivery process, that should be handled as a separate implementation requirement with Bead.

#### Typical integration flows

**Review batches for a merchant**

Goal: show batch activity for one merchant.

High level steps:

1. Identify the merchant ID.
2. Retrieve batches filtered by merchant ID and date range.
3. Display batch status, type, batch period, gross fundable amount, total fees, net fundable amount, and transaction count.
4. 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.

High level steps:

1. Start with a settlement ID.
2. Retrieve batches filtered by settlement ID or use the settlement batches endpoint.
3. Review each batch’s gross fundable amount, total fees, net fundable amount, transaction count, and payment IDs.
4. Compare the batch totals to the related settlement record.

**Reconcile a batch to payments**

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

High level steps:

1. Retrieve the batch record.
2. Use the `paymentIds` array to identify the payments in the batch.
3. Retrieve payment history or payment settlement detail for those payments.
4. Match batch totals, fees, and net fundable amount to your internal ledger.

**Investigate a batch question**

Goal: answer a merchant or partner question about how payments were grouped.

High level steps:

1. Search batches by merchant, settlement, date range, status, or type.
2. Review the batch status and batch period.
3. Confirm the gross fundable amount, total fees, net fundable amount, and transaction count.
4. Use the payment IDs to review the underlying payments.

#### Next steps

* Use [Settlement](/settlement.md) records when you need the broader settlement event.
* Use [Merchant Settlements](/settlement/merchant-settlements.md) for merchant-level settlement batches.
* Use [Payment Settlements](/settlement/payment-settlements.md) for payment-level settlement detail.
* Use [Deposits](/settlement/deposits.md) when you need funded movement and deposit status.
* Use [Reporting](/reporting.md) APIs when you need payment history before reviewing settlement.


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.