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 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 APIs first. For payment-level settlement detail, use Payment Settlement Detail. For funded bank movement, use Deposits.

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.

• Total transaction fees withheld across those batches.

• A deposit fee for the ACH or wire transfer used to fund the merchant.

• Any adjustments (chargebacks, refund recoveries, platform fees, holdbacks, and others).

• 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.

Query parameters

GET /Settlements and GET /Merchants/{merchantId}/settlements

Parameter	Type	Description
From	date	Start of the date range filter.
To	date	End of the date range filter.
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. Applies to GET /Settlements only.
Page	integer	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.

Date format: From and To accept date-only values (2026-06-22). ISO date-times with a .000Z suffix fail validation.

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.
batchIds	array of strings	Batch IDs included in this settlement.
payoutId	string or null	Payout reference associated with this settlement, when applicable.
grossFundableAmount	number or string	Total payment volume before fees and adjustments.
totalTransactionFees	number or string	Sum of all per-transaction fees withheld across the batches in this settlement period.
depositFees	number or string	Fee for the ACH or wire transfer used to fund this settlement.
adjustments	array of Adjustment	List of adjustments applied to this settlement. See Adjustments.
netFundableAmount	number or string	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 ± adjustments

For residual reporting, the revenue Bead retained from a merchant for a settlement period is:

retained = grossFundableAmount − netFundableAmount

See Residual Reporting 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.

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	number or string	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.

Relationship to other Settlement pages

Settlements are the top-level funding record in the Settlement model.

Use Batches to understand how individual payments were grouped within a settlement period.

Use Deposits to confirm funded bank movement and deposit status for a settlement.

Use Payment Settlement Detail for payment-level settlement context and to trace payments through the settlement lifecycle.

A common pattern is:

1. Use Reporting APIs to identify payments in scope.

2. Use Settlements to review fee totals, adjustments, and net fundable amount for the period.

3. Use Batches to reconcile grouped payment activity.

4. Use Deposits 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, adjustments, 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 to retrieve 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 for the full step-by-step pattern and field-level guidance.

Next steps

• Use Residual Reporting to understand how to assemble settlement data for partner residual reporting.

• Use Batches to review grouped payment activity.

• Use Deposits to confirm funded bank movement.

• Use Payment Settlement Detail for payment-level settlement context and to trace payments through the settlement lifecycle.

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