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

Layer	What it represents
Settlement	One net funding record per merchant per settlement period. Covers all terminals under that merchant.
Batch	Groups completed payments for a merchant into a settlement batch. Not scoped per terminal.
Payment	Individual transaction. Carries terminalId, settlementId, and batchId fields.

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 — retrieve payment history scoped to a terminal via GET /Terminals/{id}/payments

• Settlements — settlement record structure, query parameters, and field definitions

• Payment Settlement Detail — how to trace a payment through the settlement lifecycle using settlementId, batchId, and batchStatus

• Batches — batch record structure and relationship to settlements