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

# Residual Reporting

Residual reporting gives partners visibility into the fee revenue Bead collected across their merchant portfolio during a settlement period.

Bead operates on a net daily settlement model: fees are withheld from each merchant's gross payment volume before funds are settled into the merchant's account. Those fees accumulate through the settlement period and are reconciled at month end.

This page explains where revenue and fee data lives in the Bead API and how to assemble it for a monthly residual report.

**How Bead retains fees**

When a payment settles:

1. Bead groups completed payments into daily batches.
2. Each batch carries a `grossFundableAmount` (total payment volume) and a `totalFees` amount (transaction-based fees withheld).
3. At the end of the settlement period, Bead closes the batches into a Settlement record.
4. The Settlement record captures `totalTransactionFees` (sum of all batch fees for the period), `depositFees` (the ACH or wire fee for funding), and any `adjustments` (chargebacks, refunds, platform fees, etc.).
5. Bead funds the merchant the `netFundableAmount` — gross minus all fees and adjustments.
6. The retained fees are reconciled at month end and made available to the partner for reporting and payout purposes.

**Fee and revenue fields by entity**

| Field                           | Entity               | API field              | Notes                                                        |
| ------------------------------- | -------------------- | ---------------------- | ------------------------------------------------------------ |
| Gross payment volume            | SettlementResponse   | `grossFundableAmount`  | Total payment volume before any deductions                   |
| Transaction fees (period total) | SettlementResponse   | `totalTransactionFees` | Sum of all per-transaction fees across batches in the period |
| Transaction fees (per batch)    | PaymentBatchResponse | `totalFees`            | Per-batch subtotal; rolls up to `totalTransactionFees`       |
| Deposit / funding fee           | SettlementResponse   | `depositFees`          | ACH or wire fee for the funding transfer                     |
| Deposit / funding fee           | DepositResponse      | `feeAmount`            | Same fee, visible at the deposit record level                |
| Adjustments                     | SettlementResponse   | `adjustments[]`        | Chargebacks, refunds, platform fees, holdbacks, and others   |
| Net payout to merchant          | SettlementResponse   | `netFundableAmount`    | What the merchant received after all deductions              |

**Transaction fees are not tracked at the individual payment level.** They are aggregated at the batch level (`totalFees`) and at the settlement level (`totalTransactionFees`). If you need per-payment fee detail, contact Bead — this is not currently available in the standard API responses.

**Recommended API pattern for monthly residual reporting**

**Step 1: Identify the settlement period**

Determine the date range for the reporting month. Use `From` and `To` date filters on the `/Settlements` endpoint.

**Step 2: Retrieve settlements for the period**

```
GET /Settlements?MerchantIds[]=<merchantId>&From=<startDate>&To=<endDate>
```

Retrieve one page at a time. Use `Page` and `PageSize` (up to 100 per page). Repeat until you have all records for the period.

For partners with many merchants, pass an array of `MerchantIds` to filter to the merchants in your portfolio.

**Step 3: For each settlement, capture the revenue and fee fields**

From each `SettlementResponse`, collect:

* `merchantId`
* `id` (settlement ID)
* `grossFundableAmount`
* `totalTransactionFees`
* `depositFees`
* `adjustments` — iterate the array and note type and amount for each
* `netFundableAmount`
* `targetPayoutDate` or `settlementDate`
* `status` — filter to `dispatched` or `paid` to include only funded settlements

**Step 4: Optionally validate against batch-level fees**

To cross-check settlement-level totals against batch-level detail:

```
GET /Settlements/{id}/batches
```

Sum `totalFees` across all batches for the settlement. This should equal `totalTransactionFees` on the settlement record. If there is a discrepancy, contact Bead support.

**Step 5: Optionally validate deposit fees**

```
GET /Settlements/{id}/deposits
```

The `feeAmount` on the deposit record should match `depositFees` on the settlement. Use this when auditing funding fees.

**Adjustments**

Adjustments represent non-transaction items that modify the net settlement amount. They are included in the `adjustments` array on the `SettlementResponse` and should be reviewed when assembling a complete revenue picture for the period.

| Adjustment type         | Description                                     |
| ----------------------- | ----------------------------------------------- |
| `chargeback`            | Chargeback amount recovered from the merchant   |
| `chargebackFee`         | Fee assessed for a chargeback                   |
| `refund`                | Refund amount recovered from the merchant       |
| `achReject`             | ACH reject recovery                             |
| `holdback`              | Reserve holdback                                |
| `reversal`              | Reversal amount                                 |
| `complianceFine`        | Compliance fine assessed against the settlement |
| `platformFee`           | Platform fee assessed against the settlement    |
| `equipmentFee`          | Equipment fee assessed against the settlement   |
| `adjustmentCredit`      | Credit applied to the settlement                |
| `currencyConversionFee` | Currency conversion fee                         |
| `networkAssessmentFee`  | Network assessment fee                          |
| `depositCorrection`     | Correction to a prior deposit                   |
| `taxWithholding`        | Tax withholding amount                          |

Review the `note` field on each adjustment when present — it provides additional context for the specific item.

**Example: fee data for a single merchant over one month**

Assume Bead closed three settlements for a merchant during the month.

| Settlement | Gross   | Transaction Fees | Deposit Fee | Adjustments        | Net to Merchant |
| ---------- | ------- | ---------------- | ----------- | ------------------ | --------------- |
| S-001      | $20,000 | $480             | $0.25       | -$150 (chargeback) | $19,669.75      |
| S-002      | $18,000 | $432             | $0.25       | none               | $17,567.75      |
| S-003      | $12,000 | $288             | $0.25       | +$50 (credit)      | $11,761.75      |

For the period, the data available to the partner is:

* Total gross volume: $50,000
* Total transaction fees: $1,200
* Total deposit fees: $0.75
* Net adjustments: -$100 (chargeback net of credit)
* Total net to merchant: $49,000

This is the revenue and fee data Bead surfaces per merchant per settlement period. How partners apply this data to their internal payout schedules is handled outside the Bead API.

**Pagination and data completeness**

The `/Settlements` endpoint returns up to 100 records per page. For partners with large merchant portfolios or long reporting windows, paginate fully before computing totals.

Check that all settlements in the period have a `status` of `dispatched` or `paid` before including them in a final report. Settlements in `hold` or `cleared` state have not yet been funded and may change before month end.

**Multi-merchant portfolios**

Use the `MerchantIds` array filter to limit results to the merchants in your portfolio. Retrieve and aggregate per merchant to build a complete revenue picture across your book for the period.

**Next steps**

* Use [Settlements](/settlement.md) to retrieve settlement records and fee fields.
* Use [Batches](/settlement/batches.md) to validate batch-level fee totals.
* Use [Deposits](/settlement/deposits.md) to validate deposit fees.
* Use [Merchant Settlements](/settlement/merchant-settlements.md) for the merchant-level settlement event view.
* Use [Reporting](/reporting.md) APIs when you need the underlying payment activity for a period.
* Contact Bead if you need per-payment fee detail or a custom settlement export.


---

# 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/residual-reporting.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.