> 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. > **Building a report for a Split Funding Program partner?** The settlement-level fields on this page cover standard processing residuals. They are not the source of truth for a split funding partner distribution. See [Split Funding Program merchants](#split-funding-program-merchants) below. **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, and others), along with `netAdjustmentTotal`, the signed sum of those adjustments. 5. Bead funds the merchant the `netFundableAmount`, which is gross minus all fees plus the signed adjustment total. 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 | | Rolled-up fee total | SettlementResponse | `totalFees` | The settlement's own single fee total for the period | | Adjustments | SettlementResponse | `adjustments[]` | Chargebacks, refunds, platform fees, holdbacks, and others | | Adjustments (signed total) | SettlementResponse | `netAdjustmentTotal` | Signed sum of `netAdjustment` across `adjustments[]` | | Batch count for the period | SettlementResponse | `batchCount` | Number of batches rolled into the settlement | | Net payout to merchant | SettlementResponse | `netFundableAmount` | What the merchant received after all deductions | | Partner portion (informational) | Settlement report row (`SettlementReportRow`) | `partnerPortion` | Sum of the partner portion across the settlement's split funding payments; not part of the payable math. Not the distribution source of truth. See below. This field is not on `SettlementResponse`; read it from the settlement report. | | Split funding payment count | Settlement report row (`SettlementReportRow`) | `splitFundingTransactionCount` | Number of split funding payments in the settlement. Not on `SettlementResponse`; read it from the settlement report. | **Transaction fees are not tracked at the individual payment level for standard processing.** 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. `From` and `To` bound the settlement created-date window in UTC. They filter on the settlement's `created` date, not on `settlementDate`, and they are date-only values (`2026-06-01`). A full ISO timestamp with a time component fails validation. If your report needs to be organized by actual settlement date, retrieve by created-date window and then group on `settlementDate` yourself. **Step 2: Retrieve settlements for the period** ``` GET /Settlements?MerchantIds[]=&From=&To= ``` Retrieve one page at a time. `Page` is zero-based and defaults to 0. `PageSize` defaults to 50 and accepts up to 100. 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` * `totalFees` * `adjustments`, iterating the array and noting type and amount for each * `netAdjustmentTotal` * `netFundableAmount` * `settlementDate` (nullable; populated once the settlement has an actual settlement date) * `status`, filtered to `dispatched` or `paid` to include only funded settlements There is no `targetPayoutDate` field on `SettlementResponse`. The only date fields on the record are `settlementDate`, `created`, and `updated`. Use `settlementDate` for the actual settlement date and `created` for the window the `From` and `To` filters act on. **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,369.75 | | S-002 | $18,000 | $432 | $0.25 | none | $17,567.75 | | S-003 | $12,000 | $288 | $0.25 | +$50 (credit) | $11,761.75 | Each row is gross minus transaction fees minus the deposit fee plus the signed adjustment total: * S-001: 20,000 - 480 - 0.25 - 150 = 19,369.75 * S-002: 18,000 - 432 - 0.25 = 17,567.75 * S-003: 12,000 - 288 - 0.25 + 50 = 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: $48,699.25 The period total reconciles both ways: 50,000 - 1,200 - 0.75 - 100 = 48,699.25, and 19,369.75 + 17,567.75 + 11,761.75 = 48,699.25. 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. `Page` is zero-based and defaults to 0, and `PageSize` defaults to 50, so a request that does not set `PageSize` returns 50 records per page rather than 100. 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. When a settlement is in `hold`, read `holdReason` for the reason it is held. **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. #### Split Funding Program merchants A merchant enrolled in the [Split Funding Program](/split-funding.md) settles split funding payments at `merchantPortion` with no transaction fee, and the withheld difference is paid to the partner separately, on its own cadence, net of Bead's fee. This is a fundamentally different revenue flow from standard residual reporting, and the two should not be blended in the same calculation. > **Split funding payments do not generate residuals.** Residual reporting derives partner revenue from fees Bead withheld from the merchant. On the Split Funding Program the merchant is charged nothing, so there is no fee to derive a residual from, and the partner's margin has already been paid to them through the distribution. A partner cannot be paid a residual and a split funding distribution on the same payment. If a partner moves traffic onto the program, residual revenue on that traffic stops and is replaced by the distribution. Build residual reports from non-split-funding payments only. > **Expect the distribution to differ from the residual it replaces.** A residual derives from fees Bead charged the merchant. A split funding distribution is the consumer fee the partner collected, less Bead's fee on the merchant portion and the settlement fees. They are calculated from entirely different things and will not be the same size. Do not model a distribution as equal to the residual the same traffic would have produced. See [Bead's split funding fee](/split-funding.md#beads-split-funding-fee). The partner portion total and the split funding payment count on the settlement report are informational aggregates. They tell you split funding activity happened, not what the partner is owed. They are computed at the settlement report level, but the actual partner distribution is assessed from payments directly. This matters once refunds apply: no Bead tender currently supports a refund, but the distribution logic is already built so that a refunded or partially refunded payment would be excluded from the payout at the payment level, not the settlement level, whenever that becomes possible. **Do not use the settlement-level partner portion as a partner residual figure.** Use [Split Funding Reports](/split-funding/reports.md) instead: * The split funding transaction report gives per-payment detail. * The distribution summary gives the authoritative per-merchant, per-MID reconciliation, including Bead's fee and partner net. This is what was actually paid. **Next steps** * Use [Settlements](/settlement/settlements.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 [Payment Settlement Detail](/settlement/payment-settlement-detail.md) for the merchant-level settlement event view. * Use Reporting APIs when you need the underlying payment activity for a period. * Use [Split Funding Reports](/split-funding/reports.md) for Split Funding Program partner distributions. Do not use this page's settlement totals for that purpose. * 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.bead.xyz/settlement/residual-reporting.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.