# Settlement Records Settlement records provide the top-level view of settlement activity. Use Settlement Records when you need to review how completed payments were grouped into settlement activity, connect settlement records to batches, and reconcile settlement totals to deposit or funding activity. Settlement records are returned through Bead APIs. They are not a settlement file, statement, or custom export. #### When to use Settlement Records Use Settlement Records when you need to: * Review settlement activity across merchants or date ranges. * Retrieve a specific settlement by ID. * Connect a settlement to the batches included in it. * Connect a settlement to deposit records. * Review settlement status, type, and target payout date. * Compare gross fundable amount, fees, adjustments, and net fundable amount. * Reconcile settlement activity to internal ledger or accounting records. For payment history and transaction-level search, use Reporting APIs first. For grouped payment batches, use Batches. For merchant-level settlement activity, use Merchant Settlements. For funded movement tied to settlement, use Deposits. #### How it works A settlement record represents a settlement event for completed payment activity. A typical settlement reconciliation flow is: 1. Start with a merchant, settlement ID, or date range. 2. Retrieve settlement records using the relevant filters. 3. Review settlement status, type, target payout date, and amount fields. 4. Use batch IDs or the settlement batches endpoint to review grouped payments. 5. Use the settlement deposits endpoint to review funded movement tied to the settlement. #### Available endpoints | Scope | Path | Description | | ------------------- | ---------------------------- | -------------------------------------------------------------------------------------------------------- | | Settlement list | `/Settlements` | Returns settlement records with filters for date range, status, type, merchant, pagination, and sorting. | | Single settlement | `/Settlements/{id}` | Returns one settlement record by settlement ID. | | Settlement batches | `/Settlements/{id}/batches` | Returns batch records associated with a settlement. | | Settlement deposits | `/Settlements/{id}/deposits` | Returns deposit records associated with a settlement. | #### Shared query parameters The settlement list endpoint supports filters that help narrow results for reconciliation and support workflows. Common filters include: * `From` * `To` * `Status` * `Type` * `MerchantIds` * `Page` * `PageSize` * `SortBy` * `SortDirection` `From` and `To` use date values. `MerchantIds` accepts an array of merchant IDs. `Page` defaults to `0`, and `PageSize` defaults to `50` with a maximum of `100`. Use merchant and date filters when reviewing settlement activity for a known merchant and settlement period. Use status and type filters when reviewing settlement workflow or currency category. #### Settlement fields A settlement record can include: | Field | Type | Description | | ---------------------- | ----------------- | ----------------------------------------------------------------------------------------------- | | `id` | string | Unique settlement identifier. | | `merchantId` | string | Merchant associated with the settlement. | | `type` | string | Settlement currency category or settlement type. | | `networkTypes` | array of strings | Network types included in the settlement. | | `status` | string | Current settlement status. Expected values include `cleared`, `hold`, `dispatched`, and `paid`. | | `batchIds` | array of strings | Batch IDs included in the settlement. | | `settlementSweepId` | string or null | Optional settlement sweep identifier. | | `grossFundableAmount` | number | Gross fundable amount before fees and adjustments. | | `totalTransactionFees` | number | Total transaction fees included in the settlement. | | `depositFees` | number | Deposit fees included in the settlement. | | `adjustments` | array | Adjustments applied to the settlement. | | `netFundableAmount` | number | Net fundable amount after fees and adjustments. | | `achTransferId` | string or null | Optional ACH transfer identifier. | | `outgoingAchIds` | array of strings | Outgoing ACH identifiers associated with the settlement. | | `targetPayoutDate` | date | Target payout date for the settlement. | | `settlementDate` | date-time or null | Date and time the settlement was completed, when available. | | `created` | date-time | Date and time the settlement record was created. | | `updated` | date-time | Date and time the settlement record was last updated. | #### Settlement status Settlement status indicates the current state of the settlement. Supported status values include: * `cleared` * `hold` * `dispatched` * `paid` Use the status field to determine whether settlement activity has cleared, is on hold, has been dispatched, or has been paid. #### Settlement type Settlement type identifies the category of settlement activity. Supported type values can include: * `crypto` * `walletApps` * `fiat` Use the type field when separating crypto, wallet app, and fiat settlement activity. #### Adjustments Adjustments represent changes applied to the settlement amount. An adjustment can include: | Field | Type | Description | | --------------- | -------------- | ------------------------------------------------ | | `type` | string | Adjustment type. | | `note` | string or null | Optional note describing the adjustment. | | `netAdjustment` | number | Net adjustment amount applied to the settlement. | Adjustment types can include items such as chargebacks, refunds, ACH rejects, holdbacks, reversals, platform fees, currency conversion fees, deposit corrections, and tax withholding. #### Relationship to other Settlement pages Settlement Records are the top-level settlement view. Use Settlement Records when you need the overall settlement event. Use Batches when you need to understand which payments were grouped into that settlement. Use Deposits when you need to confirm funded movement tied to the settlement. Use Payment Settlements when you need payment-level settlement detail. Use Merchant Settlements when you need a merchant-level settlement event. A common pattern is: 1. Use [Reporting](/reporting.md) APIs to find completed payments. 2. Use [Settlement Records](/settlement/settlement-records.md) to review the settlement event. 3. Use [Batches](/settlement/batches.md) to understand grouped payment activity. 4. Use [Payment Settlements](/settlement/payment-settlements.md) for payment-level settlement detail. 5. Use [Deposits](/settlement/deposits.md) to confirm funded movement and deposit status. #### Files, exports, and API reporting Settlement record data is available through Bead APIs. Most integrations should use the documented API responses for settlement reconciliation. If a partner needs a custom export or file delivery process, that should be handled as a separate implementation requirement with Bead. #### Typical integration flows **Review settlement activity** Goal: show settlement activity for a merchant or date range. High level steps: 1. Retrieve settlement records using merchant and date filters. 2. Display settlement status, type, target payout date, gross fundable amount, total fees, adjustments, and net fundable amount. 3. Allow the user to select a settlement for batch and deposit detail. **Reconcile a settlement to batches** Goal: understand which batches are included in a settlement. High level steps: 1. Start with a settlement ID. 2. Retrieve the settlement record. 3. Review the `batchIds` array or use the settlement batches endpoint. 4. Retrieve batch records to review payment grouping, totals, and payment IDs. **Reconcile a settlement to deposits** Goal: confirm funded movement for a settlement. High level steps: 1. Start with a settlement ID. 2. Retrieve the settlement record. 3. Use the settlement deposits endpoint to retrieve deposit records tied to the settlement. 4. Compare deposit amounts and status to the settlement’s net fundable amount and target payout date. **Investigate a settlement question** Goal: answer a merchant or partner question about a settlement event. High level steps: 1. Search settlements by merchant, date range, status, or type. 2. Review the settlement status and updated timestamp. 3. Confirm gross fundable amount, total transaction fees, deposit fees, adjustments, and net fundable amount. 4. Use Batches, Payment Settlements, or Deposits for additional detail. #### Next steps * 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 [Merchant Settlements](/settlement/merchant-settlements.md) for merchant-level settlement events. * Use [Payment Settlements](/settlement/payment-settlements.md) for payment-level settlement detail. * Use [Reporting](/reporting.md) APIs when you need payment history before reviewing settlement. --- # Agent Instructions: 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: ``` GET https://developers.bead.xyz/settlement/settlement-records.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.