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

# Settlements

Settlements represent the periodic funding events that group completed payment batches into a single net payout for a merchant.

Use Settlements when you need to review the fee breakdown behind a funding event, reconcile gross and net amounts, investigate adjustments, or build residual or revenue-share reports for a settlement period.

If you are building partner residual reporting, start here. The Settlement record is the authoritative source for total transaction fees, deposit fees, adjustments, and net fundable amount for a settlement period. See [Residual Reporting](/settlement/residual-reporting.md) for the full integration pattern.

**When to use Settlements**

Use Settlements when you need to:

* Review the gross amount, total transaction fees, deposit fees, adjustments, and net fundable amount for a settlement period.
* Confirm the settlement date for a merchant.
* Connect a settlement to the batches and deposits associated with it.
* Build monthly or periodic residual or revenue-share reports.
* Investigate settlement-level fee or adjustment activity.
* Match a Bead settlement to your internal ledger or accounting system.

For payment history and transaction-level search, use [Reporting](/reporting.md) APIs first. For payment-level settlement detail, use [Payment Settlements](/settlement/payment-settlements.md). For merchant-level settlement batches, use [Merchant Settlements](/settlement/merchant-settlements.md). For funded bank movement, use [Deposits](/settlement/deposits.md).

**How it works**

A settlement is created when Bead closes a period of batch activity for a merchant and prepares a net payout.

The settlement record rolls up:

* The gross fundable amount from all batches in the period.
* Total transaction fees withheld across those batches.
* A deposit fee for the ACH or wire transfer used to fund the merchant.
* Any adjustments (chargebacks, refund recoveries, platform fees, holdbacks, and others).
* The resulting net fundable amount, which is the amount dispatched to the merchant.

A typical settlement review flow is:

1. Retrieve settlement records for a merchant and date range.
2. Review gross fundable amount, total transaction fees, deposit fees, adjustments, and net fundable amount.
3. Use the batch IDs to connect the settlement to grouped payment activity.
4. Use the deposit records to confirm funded movement and funding method.
5. Use the settlement record as the basis for any residual or revenue-share calculation.

**Available endpoints**

| Scope                     | Path                             | Description                                                                                     |
| ------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------- |
| Settlement list           | `GET /Settlements`               | Returns settlement records with filters for date range, status, type, merchant, and pagination. |
| Single settlement         | `GET /Settlements/{id}`          | Returns one settlement record by ID.                                                            |
| Batches for a settlement  | `GET /Settlements/{id}/batches`  | Returns batch records associated with a settlement.                                             |
| Deposits for a settlement | `GET /Settlements/{id}/deposits` | Returns deposit records associated with a settlement.                                           |

**Query parameters**

The settlement list endpoint supports the following filters:

| Parameter       | Type             | Description                                                     |
| --------------- | ---------------- | --------------------------------------------------------------- |
| `From`          | date             | Start of the date range filter.                                 |
| `To`            | date             | End of the date range filter.                                   |
| `Status`        | string           | Filter by settlement state. See Settlement state.               |
| `Type`          | string           | Filter by currency category: `crypto`, `walletApps`, or `fiat`. |
| `MerchantIds`   | array of strings | Filter by one or more merchant 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`.                                |

**Settlement fields**

A settlement record includes:

| Field                  | Type                | Description                                                                            |
| ---------------------- | ------------------- | -------------------------------------------------------------------------------------- |
| `id`                   | string              | Unique settlement identifier.                                                          |
| `merchantId`           | string              | Merchant associated with the settlement.                                               |
| `type`                 | string              | Settlement currency category.                                                          |
| `networkTypes`         | array of strings    | Network types included in the settlement.                                              |
| `status`               | string              | Current settlement state. See Settlement state.                                        |
| `batchIds`             | array of strings    | Batch IDs included in this settlement.                                                 |
| `payoutId`             | string or null      | Payout reference associated with this settlement, when applicable.                     |
| `grossFundableAmount`  | number or string    | Total payment volume before fees and adjustments.                                      |
| `totalTransactionFees` | number or string    | Sum of all per-transaction fees withheld across the batches in this settlement period. |
| `depositFees`          | number or string    | Fee for the ACH or wire transfer used to fund this settlement.                         |
| `adjustments`          | array of Adjustment | List of adjustments applied to this settlement. See Adjustments.                       |
| `netFundableAmount`    | number or string    | Net amount funded to the merchant after fees and adjustments.                          |
| `outgoingAchIds`       | array of strings    | Outgoing ACH identifiers associated with the settlement.                               |
| `settlementDate`       | date-time or null   | Actual settlement date, when completed.                                                |
| `created`              | date-time           | Date and time the settlement record was created.                                       |
| `updated`              | date-time           | Date and time the settlement record was last updated.                                  |

**Net fundable amount formula**

The `netFundableAmount` represents what Bead funds to the merchant after all deductions:

`netFundableAmount = grossFundableAmount − totalTransactionFees − depositFees ± adjustments`

For residual reporting, the revenue Bead retained from a merchant for a settlement period is:

`retained = grossFundableAmount − netFundableAmount`

See [Residual Reporting](/settlement/residual-reporting.md) for the full partner integration pattern.

**Settlement state**

Settlement state indicates where the settlement is in the funding lifecycle.

| Value        | Description                                                           |
| ------------ | --------------------------------------------------------------------- |
| `cleared`    | Settlement has cleared and is ready for funding.                      |
| `hold`       | Settlement is on hold and pending review before funding proceeds.     |
| `dispatched` | Settlement funds have been dispatched to the merchant's bank account. |
| `paid`       | Settlement funds have been confirmed as paid.                         |

**Adjustments**

Adjustments modify the net fundable amount and represent non-transaction items applied to a settlement.

An adjustment object includes:

| Field           | Type             | Description                                                        |
| --------------- | ---------------- | ------------------------------------------------------------------ |
| `type`          | string           | Adjustment category. See adjustment types below.                   |
| `note`          | string or null   | Optional note describing the adjustment.                           |
| `netAdjustment` | number or string | The adjustment amount. Negative values reduce net fundable amount. |

Supported adjustment types:

| Type                    | Description                                                   |
| ----------------------- | ------------------------------------------------------------- |
| `chargeback`            | Chargeback amount recovered from settlement.                  |
| `chargebackFee`         | Fee assessed for a chargeback.                                |
| `refund`                | Refund amount recovered from settlement.                      |
| `achReject`             | ACH reject recovery applied to settlement.                    |
| `holdback`              | Reserve holdback applied to settlement.                       |
| `reversal`              | Reversal amount applied to settlement.                        |
| `complianceFine`        | Compliance fine assessed against settlement.                  |
| `platformFee`           | Platform fee assessed against settlement.                     |
| `equipmentFee`          | Equipment fee assessed against settlement.                    |
| `adjustmentCredit`      | Credit applied to settlement (increases net fundable amount). |
| `currencyConversionFee` | Fee for currency conversion applied to settlement.            |
| `networkAssessmentFee`  | Network assessment fee applied to settlement.                 |
| `depositCorrection`     | Correction to a prior deposit applied to settlement.          |
| `taxWithholding`        | Tax withholding amount applied to settlement.                 |

When reviewing adjustments for residual reporting, negative adjustments reduce the amount Bead retains and should be accounted for in revenue-share calculations.

**Relationship to other Settlement pages**

Settlements are the top-level funding record in the Settlement model.

* Use [Batches](/settlement/batches.md) to understand how individual payments were grouped within a settlement period.
* Use [Deposits](/settlement/deposits.md) to confirm funded bank movement and deposit status for a settlement.
* Use [Merchant Settlements](/settlement/merchant-settlements.md) for the merchant-level settlement event view.
* Use [Payment Settlements](/settlement/payment-settlements.md) for payment-level settlement detail.

A common pattern is:

1. Use [Reporting](/reporting.md) APIs to identify payments in scope.
2. Use Settlements to review fee totals, adjustments, and net fundable amount for the period.
3. Use [Batches](/settlement/batches.md) to reconcile grouped payment activity.
4. Use [Deposits](/settlement/deposits.md) to confirm funded movement.

**Typical integration flows**

**Review settlement fee breakdown for a merchant**

Goal: understand gross amount, fees, adjustments, and net payout for a settlement period.

High level steps:

1. Retrieve settlement records for the merchant and date range.
2. Review `grossFundableAmount`, `totalTransactionFees`, `depositFees`, `adjustments`, and `netFundableAmount`.
3. Apply the net fundable amount formula to verify the net payout.
4. Review any adjustments for type and amount.

**Connect a settlement to batches and payments**

Goal: reconcile a settlement back to the grouped payments behind it.

High level steps:

1. Retrieve the settlement record.
2. Use `batchIds` to retrieve the associated batches via `GET /Settlements/{id}/batches`.
3. Use batch `paymentIds` to retrieve the underlying payments.
4. Verify that batch-level fee totals roll up to the settlement's `totalTransactionFees`.

**Reconcile a settlement to a deposit**

Goal: confirm that a settlement was funded and match the funded amount.

High level steps:

1. Retrieve the settlement record.
2. Use `GET /Settlements/{id}/deposits` to retrieve associated deposits.
3. Review deposit `amount`, `feeAmount`, `status`, and `dispatchedDate`.
4. Confirm that the deposit `feeAmount` matches the settlement `depositFees`.

**Build a monthly residual report**

Goal: calculate revenue retained by Bead per merchant for a settlement period for partner residual reporting.

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

**Next steps**

* Use [Residual Reporting](/settlement/residual-reporting.md) to understand how to assemble settlement data for partner residual reporting.
* Use [Batches](/settlement/batches.md) to review grouped payment activity.
* Use [Deposits](/settlement/deposits.md) to confirm funded bank movement.
* Use [Merchant Settlements](/settlement/merchant-settlements.md) for merchant-level settlement events.
* Use [Payment Settlements](/settlement/payment-settlements.md) for payment-level detail.
* Use [Reporting](/reporting.md) APIs when you need payment history before reviewing settlement.


---

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