> 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/faqs-and-troubleshooting/settlement-faqs/can-i-filter-settlements-or-batches-by-terminal-id.md).

# Can I filter settlements or batches by terminal ID?

No. Settlement and batch records in Bead are issued at the **merchant level**, not the terminal level. There is no `TerminalIds` filter on `GET /Settlements` or `GET /Settlements/{id}/batches`.

This is a common point of friction for integrators coming from traditional payment providers, where end-of-day batching happens at the terminal and settlement rolls up from there. Bead's model works in the opposite direction.

### How Bead settlement is structured

<table><thead><tr><th width="123">Layer</th><th>What it represents</th></tr></thead><tbody><tr><td><strong>Settlement</strong></td><td>One net funding record per merchant per settlement period. Covers all terminals under that merchant.</td></tr><tr><td><strong>Batch</strong></td><td>Groups completed payments for a merchant into a settlement batch. Not scoped per terminal.</td></tr><tr><td><strong>Payment</strong></td><td>Individual transaction. Carries <code>terminalId</code>, <code>settlementId</code>, and <code>batchId</code> fields.</td></tr></tbody></table>

A single settlement record rolls up all payment activity across every terminal and location under a merchant for that period. The `GET /Settlements` endpoint supports filtering by `MerchantIds`, `From`, `To`, `Status`, and `Type` — but not by terminal.

### How to get terminal-level payment activity

Use the **Reporting APIs** to retrieve payment records scoped to a terminal, then use the settlement fields on each record to connect back to settlement.

**Option 1: Terminal Payments endpoint**

```
GET /Terminals/{id}/payments
```

Returns all payment records for a specific terminal. Each `PaymentResponse` includes:

* `terminalId` — confirms the terminal
* `batchId` — which batch this payment belongs to
* `settlementId` — which settlement covers this payment
* `batchStatus` — current settlement lifecycle status

**Option 2: Merchant Payments with client-side filtering**

```
GET /Merchants/{merchantId}/payments
```

Retrieve all payments for a merchant and filter by `terminalId` in your own code. Useful when you need to aggregate across multiple terminals in a single call.

### Recommended reconciliation pattern for terminal-level attribution

1. Use `GET /Terminals/{id}/payments` (or merchant payments filtered by `terminalId`) to identify the payments that originated at a specific terminal.
2. Note the `settlementId` and `batchId` on each payment record.
3. Use `GET /Settlements/{id}` to retrieve the settlement covering those payments and review gross amount, fees, adjustments, and net fundable amount.
4. Use `GET /Settlements/{id}/batches` to see batch-level groupings for that settlement period.

Because settlement fees and adjustments apply at the merchant level, there is no API-native way to split settlement fees by terminal. If you need terminal-level fee attribution for reporting purposes, you will need to prorate fees proportionally by payment volume per terminal.

### Why Bead works this way

Bead settles and funds at the merchant level because the merchant is the contracted entity — the ACH or wire transfer goes to the merchant's bank account, and fees and adjustments are calculated on the full merchant settlement period rather than per-device. This differs from traditional ISO/acquiring models where each terminal holds its own batch and generates a separate settlement record.

### Related

* [Terminal Payments](/reporting/terminal-payments.md) — retrieve payment history scoped to a terminal via `GET /Terminals/{id}/payments`
* [Settlements](/settlement/settlements.md) — settlement record structure, query parameters, and field definitions
* [Payment Settlement Detail](/settlement/payment-settlement-detail.md) — how to trace a payment through the settlement lifecycle using `settlementId`, `batchId`, and `batchStatus`
* [Batches](/settlement/batches.md) — batch record structure and relationship to settlements


---

# 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/faqs-and-troubleshooting/settlement-faqs/can-i-filter-settlements-or-batches-by-terminal-id.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.