> 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.md).

# Settlement

The Settlement section helps integrators understand how completed payments are grouped, calculated, funded, and reconciled.

Use Settlement when you need to connect completed payment activity to settlement records, batch groupings, payment-level settlement detail, and deposit or funding information.

Settlement works together with Payments and [Reporting](/reporting.md):

* Payments describe individual transactions.
* [Reporting](/reporting.md) APIs return payment history by partner, merchant, terminal, tender type, status, date range, and reference.
* Settlement APIs explain how completed payments were grouped, settled, and funded.

If you need payment search or transaction history, start with [Reporting](/reporting.md). If you need settlement grouping, fee breakdowns, payout timing, funding status, or reconciliation details, use Settlement.

Building residual or revenue-share reports? Start with [Settlements](/settlement/settlements.md). It is the authoritative source for transaction fees, deposit fees, adjustments, and net fundable amount per settlement period. Then see the [Residual Reporting](/settlement/residual-reporting.md) guide for the full integration pattern.

#### When to use Settlement

Use Settlement when you need to:

* Review gross amount, fees, adjustments, and net payout for a settlement period.
* Show merchant settlement history.
* Build daily or monthly reconciliation jobs.
* Build partner residual reporting.
* Connect settled funds back to individual payments.
* Review batch-level settlement activity.
* Check payment-level settlement status.
* Confirm deposit or funding information.
* Investigate settlement-related support questions.
* Match Bead settlement activity to your internal ledger or accounting system.

#### How it works

Settlement starts after a payment has completed and becomes eligible for settlement.

A typical reconciliation flow is:

1. Use [Reporting](/reporting.md) APIs to identify the payments you care about.
2. Use `GET /Merchants/{merchantId}/settlements` to retrieve settlement records for a merchant.
3. Use [Settlement](/settlement/settlements.md) records to review period-level fee totals, adjustments, and net fundable amount.
4. Use `GET /Settlements/{id}/batches` to review batch-level groupings and connect settlements back to payments.
5. Use payment settlement fields on each PaymentResponse to review payment-level settlement status.
6. Use [Batches](/settlement/batches.md) and [Deposits](/settlement/deposits.md) when you need to reconcile funded amounts back to payments.

#### Core settlement concepts

**Settlements**

A settlement is the top-level funding record for a settlement period. It rolls up all batch activity for a merchant into a single record that captures gross fundable amount, total transaction fees, deposit fees, adjustments, and net fundable amount.

Use [Settlements](/settlement/settlements.md) when you need fee totals, net payout amounts, adjustment detail, or the basis for residual and revenue-share reporting. Retrieve settlement records for a specific merchant using `GET /Merchants/{merchantId}/settlements`.

**Payments**

A payment is the original transaction created through the Payments API. Payment records include transaction-level information such as amount, tender type, status, merchant, terminal, reference, and tracking identifiers.

Every PaymentResponse includes settlement fields (`settlementId`, `batchId`, `batchPeriod`, `batchStatus`) that show where the payment sits in the settlement lifecycle. These fields populate as the payment moves through batching and settlement.

**Payment settlement detail**

Payment settlement detail explains how individual payments connect to settlement activity, including which batch they belong to, which settlement covers them, and their current settlement status.

Use payment settlement detail when you need to understand how an individual payment settled, which batch it belongs to, the settlement status, and when it was included in a settlement. See [Payment Settlement Detail](/settlement/payment-settlement-detail.md).

**Batches**

Batches group payments for settlement processing and reconciliation.

Use [Batches](/settlement/batches.md) when you need to understand which payments were grouped together, review batch-level fee totals, and how they relate to a settlement record.

**Deposits**

Deposits represent funding activity associated with settlement.

Use [Deposits](/settlement/deposits.md) when you need to confirm funded amounts, deposit status, deposit method, deposit fees, or the settlement record associated with a deposit.

#### Relationship to Reporting

[Reporting](/reporting.md) focuses on payment history. Use Reporting APIs when you need lists of payments and transaction-level fields.

Settlement focuses on how completed payments were grouped, calculated, and funded. Use Settlement APIs when you need settlement fee breakdowns, batch relationships, payment-level settlement context, deposit information, and settlement status.

A common pattern is to use [Reporting](/reporting.md) APIs to find the payments for a report or investigation, then use Settlement APIs to understand how those payments were settled and funded.

#### Files, exports, and API reporting

Bead exposes settlement, batch, deposit, and payment-level settlement data through APIs.

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

#### Typical integration flows

**Merchant settlement history**

Goal: show settlement history for a merchant.

1. Identify the merchant in Bead.
2. Retrieve settlement records using `GET /Merchants/{merchantId}/settlements`.
3. Display settlement amount, status, settlement date, and net fundable amount.
4. Allow the user to select a settlement for batch and payment-level detail.

**Payment-level settlement review**

Goal: explain how a specific payment settled.

1. Start with a payment from [Reporting](/reporting.md) APIs or a known payment identifier.
2. Retrieve the payment using `GET /Merchants/{merchantId}/payments` and review `settlementId`, `batchId`, `batchPeriod`, and `batchStatus` on the PaymentResponse.
3. If `settlementId` is set, retrieve the settlement using `GET /Settlements/{id}` to review fee totals and net fundable amount.
4. Use `GET /Settlements/{id}/batches` for batch context and to connect the payment to the broader settlement.

**Deposit reconciliation**

Goal: reconcile funded deposits back to settlement activity.

1. Review the deposit record.
2. Use the related settlement information to identify the settlement activity behind the deposit.
3. Review batch and payment-level settlement information as needed.
4. Match deposit amount, settlement status, fees, and related payment activity to your internal ledger.

**Residual and revenue-share reporting**

Goal: calculate the revenue Bead retained on behalf of a partner for a settlement period for use in partner residual reporting.

1. Retrieve settlement records for the merchant and date range.
2. Review `grossFundableAmount`, `totalTransactionFees`, `depositFees`, `adjustments`, and `netFundableAmount` on each settlement.
3. Compute retained revenue per merchant per period.
4. Apply your internal payout schedule to produce residual amounts.

See [Residual Reporting](/settlement/residual-reporting.md) for the full step-by-step pattern and field-level guidance.

**Support investigation**

Goal: answer a merchant or partner question about settlement timing or funding.

1. Use [Reporting](/reporting.md) APIs to locate the original payment or group of payments.
2. Review `settlementId`, `batchId`, and `batchStatus` on the PaymentResponse to check settlement status.
3. Use `GET /Settlements/{id}/batches` to understand the batch-level settlement event.
4. Review [Deposits](/settlement/deposits.md) if the question is about funded movement to the destination account.

#### Next steps

* Use [Settlements](/settlement/settlements.md) for period-level fee totals, adjustments, and net fundable amount.
* Use [Residual Reporting](/settlement/residual-reporting.md) to build partner residual reports.
* Use [Payment Settlement Detail](/settlement/payment-settlement-detail.md) for payment-level settlement context and to trace payments through the settlement lifecycle.
* Use [Batches](/settlement/batches.md) when you need grouped payment batch records.
* Use [Deposits](/settlement/deposits.md) when you need funded movement and deposit status.
* Use [Reporting](/reporting.md) when you need payment history before reviewing settlement.
* Review Settlement status codes in the [Reference Guide](/reference-guide.md) when interpreting settlement states.
* Review Settlement currencies in the [Reference Guide](/reference-guide.md) when interpreting settlement currency and tender information.


---

# 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.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.