> 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 Settlement Detail](/settlement/payment-settlement-detail.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. * The number of batches included in the period, as `batchCount`. * Total transaction fees withheld across those batches. * A deposit fee for the ACH or wire transfer used to fund the merchant. * A rolled-up fee total for the settlement, as `totalFees`. * Any adjustments (chargebacks, refund recoveries, platform fees, holdbacks, and others), plus their signed sum as `netAdjustmentTotal`. * 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. | | Merchant settlement list | GET /Merchants/{merchantId}/settlements | Returns settlement records for a specific merchant. | | 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. | `GET /Settlements/{id}` accepts no query parameters. Only the path `id` is required. **Query parameters** **GET /Settlements and GET /Merchants/{merchantId}/settlements** | Parameter | Type | Description | | ------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | From | date | Start of the settlement created-date window (UTC). Filters on the settlement's `created` date, not on `settlementDate`. | | To | date | End of the settlement created-date window (UTC). Filters on the settlement's `created` date, not on `settlementDate`. | | 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. Functions on GET /Settlements only. Accepted but ignored on GET /Merchants/{merchantId}/settlements, which is already scoped by its path parameter. See the callout below. | | Page | integer | Zero-based page number. Defaults to 0. | | PageSize | integer | Results per page. Defaults to 50, maximum 100. | | SortBy | string | Field to sort by. See Sortable fields. | | SortDirection | string | Sort direction: asc or desc. | > **`MerchantIds` has no effect on `GET /Merchants/{merchantId}/settlements`.** The parameter is accepted and returns HTTP 200, but it does not change the result set: passing a different merchant's ID returns the same records as the unfiltered request, all still belonging to the merchant in the path. Confirmed by direct testing. The path parameter is the only merchant scope on that endpoint. Use `GET /Settlements` with `MerchantIds` when you want to query several merchants in one call, which is also the more efficient pattern for portfolio reconciliation. See [Settlement Reconciliation Patterns](/settlement/settlement-reconciliation-patterns.md). > **Date format:** `From` and `To` accept date-only values (`2026-06-22`). They are date-only parameters: a full ISO date-time with a time component, including an ISO date-time with a `.000Z` suffix, fails validation. Confirmed on `GET /Settlements` and `GET /Batches` by direct testing. > **`To` appears to be exclusive.** A same-day window (`From` and `To` set to the same date) returns zero records, while extending `To` by one day returns the expected record. Extend `To` past the last day you want included. This boundary behavior was observed in testing but has not been formally confirmed with engineering. > **What the date window filters:** `From` and `To` bound the settlement's created-date window in UTC. They do not filter on `settlementDate`. If you need to report by actual settlement date, retrieve records by created-date window and then filter or sort on `settlementDate` yourself. **GET /Settlements/{id}/batches** | Parameter | Type | Description | | ------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | From | date | Start of the date-only window (UTC). | | To | date | End of the date-only window (UTC). | | Status | string | Filter by batch status: open, closed, or hold. | | Type | string | Filter by currency category: crypto, walletApps, or fiat. | | MerchantIds | array of strings | Filter by one or more merchant IDs. Not verified as functional on this path-scoped endpoint. | | SettlementIds | array of strings | Filter by one or more settlement IDs. Intersects with the path scope, it does not override it. Passing a different settlement's ID returns an empty result rather than that settlement's batches. | | Page | integer | Zero-based 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. | > **`SettlementIds` intersects, it does not override.** On `GET /Settlements/{id}/batches` the path parameter always constrains the result. Supplying `SettlementIds` for a different settlement returns an empty `data` array, not the other settlement's batches. Confirmed by direct testing. To read another settlement's batches, change the path. **GET /Settlements/{id}/deposits** | Parameter | Type | Description | | ------------- | ---------------- | ---------------------------------------------------------------------------------------------- | | From | date | Start of the date-only window (UTC). | | To | date | End of the date-only window (UTC). | | Status | string | Filter by deposit status: dispatched, paid, or error. | | Method | string | Filter by bank deposit method: ach or wire. | | MerchantIds | array of strings | Filter by one or more merchant IDs. Not verified as functional on this path-scoped endpoint. | | SettlementIds | array of strings | Filter by one or more settlement IDs. Not verified as functional on this path-scoped endpoint. | | Page | integer | Zero-based 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. | **Sortable fields** For `GET /Settlements`, `SortBy` accepts exactly these values: | Value | Sorts on | | -------------------- | ----------------------------------------- | | type | Settlement currency category. | | status | Current settlement state. | | batchCount | Number of batches in the settlement. | | grossFundableAmount | Gross payment volume. | | totalTransactionFees | Period total of per-transaction fees. | | depositFees | Funding transfer fee. | | totalFees | Rolled-up fee total for the settlement. | | netAdjustmentTotal | Signed sum of adjustments. | | netFundableAmount | Net amount funded to the merchant. | | settlementDate | Actual settlement date, when present. | | created | Settlement record creation timestamp. | | updated | Settlement record last-updated timestamp. | **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. | | holdReason | string or null | Reason the settlement is on hold. Null unless `status` is hold. | | batchIds | array of strings | Batch IDs included in this settlement. | | batchCount | int32 | Number of batches included in this settlement. | | payoutId | string or null | Payout reference associated with this settlement, when applicable. | | grossFundableAmount | double | Total payment volume before fees and adjustments. | | totalTransactionFees | double | Sum of all per-transaction fees withheld across the batches in this settlement period. | | depositFees | double | Fee for the ACH or wire transfer used to fund this settlement. | | totalFees | double | Rolled-up fee total recorded on this settlement. | | adjustments | array of Adjustment | List of adjustments applied to this settlement. See Adjustments. | | netAdjustmentTotal | double | Signed sum of the `netAdjustment` values in `adjustments`. Negative reduces net fundable amount. | | netFundableAmount | double | 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 + netAdjustmentTotal` Every term in that expression is a first-class field on the settlement record. `netAdjustmentTotal` is signed: negative adjustments such as chargebacks reduce the net, and credits such as `adjustmentCredit` increase it. `totalFees` is the settlement's own rolled-up fee total. Use it when you want a single fee figure for the period rather than the separate `totalTransactionFees` and `depositFees` components, and reconcile it against your own ledger before treating it as interchangeable with their sum. 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. | `status` is returned as a plain string in the schema. Treat these four values as the set it carries, and read `holdReason` whenever `status` is hold. **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 | double | 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. Use `netAdjustmentTotal` when you need the period's signed adjustment total without iterating the array. **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 [Payment Settlement Detail](/settlement/payment-settlement-detail.md) for payment-level settlement context and to trace payments through the settlement lifecycle. 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. 1. Retrieve settlement records for the merchant and date range using `GET /Merchants/{merchantId}/settlements`. 2. Review `grossFundableAmount`, `totalTransactionFees`, `depositFees`, `totalFees`, `adjustments`, `netAdjustmentTotal`, 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. 1. Retrieve the settlement record. 2. Use `batchIds` and `batchCount` to retrieve and count 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. 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 [Payment Settlement Detail](/settlement/payment-settlement-detail.md) for payment-level settlement context and to trace payments through the settlement lifecycle. * 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=&goal= ``` `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.