# Merchant Settlements Merchant settlements provide the merchant-level view of settlement activity. Use Merchant Settlements when you need to show settlement history for a merchant, retrieve a specific merchant settlement, or connect a merchant-level settlement event to payment-level settlement detail. Most integrations use the read operations on this page. Settlement creation and preview operations are typically used by Bead or under guidance from the Bead team. #### When to use Merchant Settlements Use Merchant Settlements when you need to: * Show settlement history for a merchant. * Retrieve a specific merchant settlement by ID. * Review the settlement amount, payout method, and status. * Understand the time window included in a merchant settlement. * Connect a merchant settlement to payment-level settlement records. * Support merchant or partner questions about a merchant settlement event. * Match a merchant settlement to your internal ledger or reporting system. For payment history and transaction-level search, use Reporting APIs first. For payment-level settlement detail, use Payment Settlements. For grouped payment batches, use Batches. For funded movement tied to settlement, use Deposits. #### How it works A merchant settlement represents a merchant-level settlement event. A typical merchant settlement review flow is: 1. Start with a merchant ID. 2. Retrieve merchant settlement records for that merchant. 3. Review the settlement amount, status, payout method, and time window. 4. Use the merchant settlement ID to retrieve related payment-level settlement detail. 5. Use Batches or Deposits when you need to reconcile the settlement to grouped payments or funded movement. #### Available endpoints | Scope | Path | Description | | ------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------ | | Merchant settlement list | `/MerchantSettlements/merchant/{merchantId}` | Returns merchant settlement records for a specific merchant. | | Single merchant settlement | `/MerchantSettlements/{merchantSettlementId}` | Returns one merchant settlement by ID. | | Payment IDs for a merchant settlement | `/MerchantSettlements/payment-ids/merchant-settlement` | Returns payment IDs associated with a merchant settlement. | #### Query parameters The merchant settlement list endpoint supports pagination and sorting. Common parameters include: * `page` * `pageSize` * `sortByDirection` `page` defaults to `0`. `pageSize` defaults to `10`. `sortByDirection` uses `ascending` or `descending`. Use `sortByDirection=descending` when displaying the most recent merchant settlements first. #### Merchant settlement fields A merchant settlement record can include: | Field | Type | Description | | ------------------------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------- | | `id` | string | Unique merchant settlement identifier. | | `merchantId` | string | Merchant associated with the settlement. | | `amount` | object | Settlement amount object. Includes amount, amount precision, and currency ID. | | `settlementPaymentType` | string | Payout method for the settlement. Supported values include `ach` and `wire`. | | `statusCode` | string | Current merchant settlement status. Supported values include `created`, `pending`, `processing`, `completed`, and `error`. | | `merchantPaymentSettlementIds` | array of strings | Payment-level settlement record IDs associated with this merchant settlement. | | `startTime` | date-time or null | Start of the payment window included in the merchant settlement, when available. | | `endTime` | date-time or null | End of the payment window included in the merchant settlement, when available. | | `quoteId` | string or null | Optional quote reference associated with the settlement. | | `transferId` | string or null | Optional transfer reference associated with the settlement. | | `transferJsonString` | string or null | Optional transfer payload used for audit or troubleshooting. | | `created` | date-time or null | Date and time the merchant settlement record was created. | | `updated` | date-time or null | Date and time the merchant settlement record was last updated. | #### Settlement amount The `amount` field uses an amount object. | Field | Type | Description | | ----------------- | ------- | ---------------------------------------------- | | `amount` | number | Numeric settlement amount. | | `amountPrecision` | integer | Number of decimal places used for the amount. | | `currencyId` | integer | Currency identifier for the settlement amount. | #### Merchant settlement status Merchant settlement status indicates the current state of the merchant settlement. Supported status values include: * `created` * `pending` * `processing` * `completed` * `error` Use the status field to determine whether a merchant settlement is newly created, in progress, complete, or requires review. #### Settlement payment type Settlement payment type identifies the payout method for the merchant settlement. Supported values include: * `ach` * `wire` #### Relationship to other Settlement pages Merchant Settlements are one part of the broader Settlement model. Use Merchant Settlements when you need the merchant-level settlement event. Use Payment Settlements when you need payment-level settlement detail. Use Batches when you need to understand grouped payment batches. Use Deposits when you need to confirm funded movement tied to settlement. A common pattern is: 1. Use [Reporting](/reporting.md) APIs to find completed payments. 2. Use [Merchant Settlements](/settlement/merchant-settlements.md) to review merchant-level settlement events. 3. Use [Payment Settlements](/settlement/payment-settlements.md) to review payment-level settlement detail. 4. Use [Batches](/settlement/batches.md) to understand grouped payment activity. 5. Use [Deposits](/settlement/deposits.md) to confirm funded movement and deposit status. #### Operations under Bead guidance Some merchant settlement endpoints preview or trigger settlement activity. These operations are typically used by Bead or under guidance from the Bead team. Use these only when Bead has confirmed they are appropriate for your integration. | Scope | Path | Description | | ------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- | | Preview settleable amount for a time window | `/MerchantSettlements/settle/window/amount` | Returns the amount that could be settled for a merchant in a specified time window. | | Preview settleable amount for a merchant | `/MerchantSettlements/settle/amount/merchant` | Returns the amount that could be settled for a merchant across eligible payments. | | Settle a time window | `/MerchantSettlements/settle/window` | Creates a merchant settlement for a specified payment window. | | Settle a merchant | `/MerchantSettlements/settle/merchant` | Creates a merchant settlement for eligible merchant activity. | #### Typical integration flows **Show merchant settlement history** Goal: show settlement history for one merchant. High level steps: 1. Identify the merchant ID. 2. Retrieve merchant settlements for the merchant. 3. Display settlement amount, status, payout method, time window, and created date. 4. Allow the user to select a merchant settlement for more detail. **Retrieve a specific merchant settlement** Goal: show detail for a known merchant settlement. High level steps: 1. Start with a merchant settlement ID. 2. Retrieve the merchant settlement record. 3. Review settlement amount, status, payout method, and time window. 4. Use related payment settlement IDs when the user needs payment-level detail. **Reconcile a merchant settlement to payments** Goal: connect a merchant settlement back to payment-level detail. High level steps: 1. Retrieve the merchant settlement record. 2. Use the `merchantPaymentSettlementIds` or payment ID endpoint to identify related records. 3. Retrieve payment-level settlement detail. 4. Match amounts, status, and settlement timing to your internal ledger. **Investigate a merchant settlement question** Goal: answer a merchant or partner question about a settlement event. High level steps: 1. Search merchant settlements for the merchant. 2. Review the settlement status and updated timestamp. 3. Confirm the settlement amount and payout method. 4. Use Payment Settlements, Batches, or Deposits for additional context. #### Next steps * Use [Payment Settlements](/settlement/payment-settlements.md) for payment-level settlement detail. * 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 [Reporting](/reporting.md) APIs when you need payment history before reviewing settlement. * Use [Settlement status codes](/reference-guide/enumerations-and-schemas/settlement-status-codes.md) in the Reference Guide when interpreting settlement states. --- # 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/merchant-settlements.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.