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 APIs to find completed payments.

2. Use Settlement Records to review the settlement event.

3. Use Batches to understand grouped payment activity.

4. Use Payment Settlements for payment-level settlement detail.

5. Use Deposits 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 when you need grouped payment batch records.

• Use Deposits when you need funded movement and deposit status.

• Use Merchant Settlements for merchant-level settlement events.

• Use Payment Settlements for payment-level settlement detail.

• Use Reporting APIs when you need payment history before reviewing settlement.