# Merchant Settlements

Merchant settlements provide the batch level view of settlement activity for a single merchant. Each merchant settlement is a batch that groups one or more payments into a single settlement event, such as a daily or intraday settlement.

Use these APIs when you need to:

* List settlement batches for a merchant
* Retrieve a specific settlement batch by its identifier
* Preview how much is currently settleable for a merchant
* In limited cases, trigger settlement for a merchant

Most integrators will use the read operations. The mutating operations are typically used by Bead or under guidance from the Bead team.

### Merchant settlement object

Merchant settlement batches are represented by the `MerchantSettlement` schema.

**Key fields**

* `id`\
  Unique identifier for this settlement batch
* `created`, `updated`\
  ISO 8601 timestamps that indicate when the batch was created and last updated
* `merchantId`\
  Identifier of the merchant this settlement belongs to
* `amount`\
  An `AmountInfo` object representing the settlement amount
  * `amount` numeric value
  * `amountPrecision` number of decimal places
  * `currencyId` currency identifier for the settlement
* `startTime`, `endTime`\
  Optional ISO 8601 timestamps that describe the window of payments included in this settlement
* `settlementPaymentType`\
  How the settlement will be paid out. Uses `SettlementPaymentType` and can be `ach` or `wire`
* `statusCode`\
  Batch level settlement status, using `MerchantSettlementStatus`\
  Typical values include `created`, `pending`, `processing`, `completed`, and `error`. See Settlement status codes in the Reference Guide for full definitions
* `merchantPaymentSettlementIds`\
  Array of identifiers for `MerchantPaymentSettlement` records attached to this batch
* `quoteId`, `transferId`, `transferJsonString`\
  Optional identifiers and raw transfer information associated with bank or provider transfers

For full field definitions, see the schema reference. The sections below focus on how to query and use merchant settlement batches.

### Merchant settlement history

Returns a paginated list of settlement batches for a single merchant.

**Endpoint**

`GET /MerchantSettlements/merchant/{merchantId}`

**Path parameters**

| Name       | Type   | Required | Description                 |
| ---------- | ------ | -------- | --------------------------- |
| merchantId | string | Yes      | Merchant identifier in Bead |

**Request headers**

| Header        | Value                   |
| ------------- | ----------------------- |
| Authorization | `Bearer <access_token>` |
| Accept        | `application/json`      |

**Query parameters**

| Name            | Type    | Required | Notes                                                                                        |
| --------------- | ------- | -------- | -------------------------------------------------------------------------------------------- |
| page            | integer | No       | Zero based page index. Defaults to `0` if omitted                                            |
| pageSize        | integer | No       | Number of items per page. Defaults to `10` if omitted                                        |
| sortByDirection | string  | No       | Sort order. Uses `SortByDirection` enum, `ascending` or `descending`. Default is `ascending` |

**Example request**

```bash
curl -G "https://api.test.devs.beadpay.io/MerchantSettlements/merchant/mer_4e5a13aa" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "page=0" \
  --data-urlencode "pageSize=20" \
  --data-urlencode "sortByDirection=descending"
```

**Successful response 200**

```json
{
  "data": [
    {
      "id": "ms_01J8Z4FH9A",
      "created": "2025-09-01T23:15:05.210Z",
      "updated": "2025-09-01T23:20:10.002Z",
      "merchantId": "mer_4e5a13aa",
      "amount": {
        "amount": 2450.75,
        "amountPrecision": 2,
        "currencyId": 101
      },
      "quoteId": "qt_9c87fe",
      "transferId": "tr_01G9C1Z3M2",
      "transferJsonString": null,
      "startTime": "2025-09-01T00:00:00Z",
      "endTime": "2025-09-01T23:59:59Z",
      "settlementPaymentType": "ach",
      "statusCode": "completed",
      "merchantPaymentSettlementIds": [
        "mps_01J8Z4FDS3",
        "mps_01J8Z4FH2Q"
      ]
    }
  ],
  "total": 1,
  "page": 0,
  "pageSize": 20
}
```

**Field reference**

| Field                        | Description                                                       |
| ---------------------------- | ----------------------------------------------------------------- |
| id                           | Unique settlement batch identifier                                |
| created, updated             | ISO 8601 timestamps for creation and last update                  |
| merchantId                   | Merchant identifier                                               |
| amount                       | Settlement amount object including value, precision, and currency |
| startTime, endTime           | Optional time window of payments included in this settlement      |
| settlementPaymentType        | Payout method for the settlement, for example `ach` or `wire`     |
| statusCode                   | Batch level settlement status. See Settlement status codes page   |
| merchantPaymentSettlementIds | Identifiers of merchant payment settlement lines in this batch    |
| quoteId, transferId          | Identifiers used for pricing and funding transfers                |
| transferJsonString           | Optional raw transfer payload for auditing or troubleshooting     |

**Error responses**

| Code | Condition                                         |
| ---- | ------------------------------------------------- |
| 401  | Missing or invalid token                          |
| 403  | Authenticated but not permitted for this merchant |
| 404  | Merchant id does not exist or is not visible      |

**Best practices**

* Use `sortByDirection=descending` to show the most recent settlements first in UIs
* Keep `pageSize` moderate for interactive use and larger for offline exports
* Store the `id` and `statusCode` in your own system if you display settlement history in a partner or merchant portal
* Use the Payment settlements endpoints to retrieve the payment level breakdown for each batch

### Retrieve a merchant settlement by id

Retrieves a single merchant settlement batch by its identifier.

**Endpoint**

`GET /MerchantSettlements/{merchantSettlementId}`

**Path parameters**

| Name                 | Type   | Required | Description                 |
| -------------------- | ------ | -------- | --------------------------- |
| merchantSettlementId | string | Yes      | Settlement batch identifier |

**Request headers**

| Header        | Value                   |
| ------------- | ----------------------- |
| Authorization | `Bearer <access_token>` |
| Accept        | `application/json`      |

**Example request**

```bash
curl "https://api.test.devs.beadpay.io/MerchantSettlements/ms_01J8Z4FH9A" \
  -H "Authorization: Bearer $TOKEN"
```

**Successful response 200**

The response body is a single `MerchantSettlement` object, with the same fields shown in the previous example.

**Error responses**

| Code | Condition                                           |
| ---- | --------------------------------------------------- |
| 401  | Missing or invalid token                            |
| 403  | Authenticated but not permitted to view this record |
| 404  | Settlement id does not exist or is not visible      |

**Usage notes**

* Use this endpoint for detail views or troubleshooting when you already know the settlement id
* For payment level details within the batch, use the endpoints documented on the Payment settlements page

### Preview settleable amount for a time window

Returns how much could be settled for a merchant in a specific time window without creating a settlement batch.

**Endpoint**

`GET /MerchantSettlements/settle/window/amount`

**Query parameters**

| Name       | Type   | Required | Notes                                             |
| ---------- | ------ | -------- | ------------------------------------------------- |
| merchantId | string | Yes      | Merchant identifier                               |
| startTime  | string | Yes      | Inclusive start time in ISO 8601 date time format |
| endTime    | string | Yes      | Inclusive end time in ISO 8601 date time format   |

**Example request**

```bash
curl -G "https://api.test.devs.beadpay.io/MerchantSettlements/settle/window/amount" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "merchantId=mer_4e5a13aa" \
  --data-urlencode "startTime=2025-09-01T00:00:00Z" \
  --data-urlencode "endTime=2025-09-01T23:59:59Z"
```

**Successful response 200**

```json
2450.75
```

The response is a numeric value representing the total amount that could be settled for this merchant in the given window, in the default settlement currency for that merchant.

### Preview settleable amount for all eligible payments

Returns how much could be settled for a merchant across all currently eligible payments, without specifying a time window.

**Endpoint**

`GET /MerchantSettlements/settle/amount/merchant`

**Query parameters**

| Name       | Type   | Required | Notes               |
| ---------- | ------ | -------- | ------------------- |
| merchantId | string | Yes      | Merchant identifier |

**Example request**

```bash
curl -G "https://api.test.devs.beadpay.io/MerchantSettlements/settle/amount/merchant" \
  -H "Authorization: Bearer $TOKEN" \
  --data-urlencode "merchantId=mer_4e5a13aa"
```

**Successful response 200**

```json
7125.30
```

Use this endpoint in internal tools when you want a quick answer to “How much is currently available to settle for this merchant” across all eligible payments.

### Settle a time window

Creates a merchant settlement batch for a merchant across a specified time window. This endpoint is typically controlled by Bead and should only be used under guidance from the Bead team.

**Endpoint**

`POST /MerchantSettlements/settle/window`

**Request headers**

| Header        | Value                   |
| ------------- | ----------------------- |
| Authorization | `Bearer <access_token>` |
| Content-Type  | `application/json`      |
| Accept        | `application/json`      |

**Request body**

`SettleFundsByPaymentWindowRequest`

| Field      | Type   | Required | Description                                       |
| ---------- | ------ | -------- | ------------------------------------------------- |
| merchantId | string | Yes      | Merchant identifier                               |
| startTime  | string | Yes      | Inclusive start of the window, ISO 8601 date time |
| endTime    | string | Yes      | Inclusive end of the window, ISO 8601 date time   |

**Example request**

```bash
curl -X POST "https://api.test.devs.beadpay.io/MerchantSettlements/settle/window" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "mer_4e5a13aa",
    "startTime": "2025-09-01T00:00:00Z",
    "endTime": "2025-09-01T23:59:59Z"
  }'
```

**Successful response**

* `200 OK` or `201 Created` with a `MerchantSettlement` object for the new batch

**Error responses**

| Code | Condition                                                       |
| ---- | --------------------------------------------------------------- |
| 400  | Invalid payload or time window                                  |
| 401  | Missing or invalid token                                        |
| 403  | Not permitted to trigger settlement for this merchant           |
| 409  | Conflicting settlement in progress or settlement rule violation |

### Settle all eligible payments for a merchant

Creates a merchant settlement batch that includes all currently eligible payments for a merchant. This is an operational control and should be used carefully.

**Endpoint**

`POST /MerchantSettlements/settle/merchant`

**Request headers**

| Header        | Value                   |
| ------------- | ----------------------- |
| Authorization | `Bearer <access_token>` |
| Accept        | `application/json`      |

**Query parameters**

| Name       | Type   | Required | Notes               |
| ---------- | ------ | -------- | ------------------- |
| merchantId | string | Yes      | Merchant identifier |

**Example request**

```bash
curl -X POST "https://api.test.devs.beadpay.io/MerchantSettlements/settle/merchant?merchantId=mer_4e5a13aa" \
  -H "Authorization: Bearer $TOKEN"
```

**Successful response**

* `200 OK` or `201 Created` with a `MerchantSettlement` object for the new batch

**Error responses**

Same as for `POST /MerchantSettlements/settle/window`.

**Usage**

* Use this endpoint only when you have agreed with Bead on how and when merchants should be settled
* Typically used in internal operations tools, not exposed directly to external integrators

### Related endpoints

The following endpoints also live under `MerchantSettlements` but are documented on the Payment settlements page:

* `GET /MerchantSettlements/merchant/between` returns payments and merchant payment settlement records for a merchant in a time window
* `GET /MerchantSettlements/settlement-info/{merchantSettlementId}` returns payments and merchant payment settlements for a specific batch
* `GET /MerchantSettlements/payment-ids/merchant-settlement` returns payment identifiers for a specific batch

Use those endpoints when you need the payment level breakdown for a settlement batch.