# GET /api/public/order-settlements

> Retrieve a paged list of OrderSettlements

- Surface: `/api/public` · operationId `listOrderSettlements` · Group: OrderSettlement
- Authorisation: Token with scope `public:order-settlements:read`
- Organisation key: needs the capability `economy:read` on the clinic
- The spec: https://developers.rivr.io/openapi/api-public.json
- The spec's introduction: https://developers.rivr.io/reference/api-public.md
- Page in the portal: https://developers.rivr.io/reference/api-public/listOrderSettlements

The examples target the sandbox (`https://api.test.rivr.io`) and need test credentials.

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `pageNumber` | query | integer (int32) | no |  |
| `pageSize` | query | integer (int32) | no |  |

## Responses

### 200

OK

`application/json`

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `orderSettlements` | OrderSettlementForLists[] |  |
| `orderSettlements[].id` | string (uuid) |  |
| `orderSettlements[].createdDate` | string (date-time) |  |
| `orderSettlements[].modifiedDate` | string (date-time) |  |
| `orderSettlements[].version` | integer (int32) | (nullable) |
| `orderSettlements[].erasedAt` | string (date-time) | (nullable) |
| `orderSettlements[].merchantId` | string (uuid) |  |
| `orderSettlements[].merchantName` | string | (nullable) |
| `orderSettlements[].currency` | string | ISO 4217 currency code |
| `orderSettlements[].preparedDate` | string (date-time) | (nullable) |
| `orderSettlements[].payoutRequestedDate` | string (date-time) | (nullable) |
| `orderSettlements[].payoutCompletedDate` | string (date-time) | (nullable) |
| `orderSettlements[].readThroughAccountBalancingDate` | string (date-time) | (nullable) |
| `orderSettlements[].reference` | string | (nullable) |
| `orderSettlements[].settlementNumber` | string | (nullable) |
| `orderSettlements[].ocr` | string | (nullable) |
| `orderSettlements[].orderDates` | DateRange |  |
| `orderSettlements[].orderDates.startDate` | string (date) |  |
| `orderSettlements[].orderDates.endDate` | string (date) |  |
| `orderSettlements[].orderDates.areSame` | boolean |  |
| `orderSettlements[].isCredit` | boolean |  |
| `orderSettlements[].settlementInfo` | DomainSettlementInfo |  |
| `orderSettlements[].settlementInfo.settlementDate` | string (date-time) | (nullable) |
| `orderSettlements[].settlementInfo.settledDate` | string (date-time) | (nullable) |
| `orderSettlements[].settlementInfo.isSettled` | boolean |  |
| `orderSettlements[].settlementInfo.isScheduled` | boolean |  |
| `orderSettlements[].settlementInfo.ledger` | Ledger |  |
| `orderSettlements[].settlementInfo.canSchedule` | boolean |  |
| `orderSettlements[].settlementInfo.canReschedule` | boolean |  |
| `orderSettlements[].settlementInfo.canSettle` | boolean |  |
| `orderSettlements[].settlementInfo.canCancel` | boolean |  |
| `orderSettlements[].settlementInfo.canCredit` | boolean |  |
| `orderSettlements[].transferInfo` | EntityTransferInfo |  |
| `orderSettlements[].transferInfo.transfers` | EntityTransfer[] |  |
| `orderSettlements[].transferInfo.pendingAcknowledgmentTransferId` | string (uuid) | (nullable) |
| `orderSettlements[].sourceBalanceAccountId` | string | (nullable) |
| `orderSettlements[].totalAmount` | Amount |  |
| `orderSettlements[].totalAmount.currencyCode` | string |  |
| `orderSettlements[].totalAmount.currency` | string | ISO 4217 currency code |
| `orderSettlements[].totalAmount.decimals` | integer (int32) |  |
| `orderSettlements[].totalAmount.value` | integer (int64) |  |
| `orderSettlements[].totalAmount.valueForView` | number (double) |  |
| `orderSettlements[].totalAmount.money` | Money |  |
| `orderSettlements[].completedCount` | integer (int32) |  |
| `orderSettlements[].refundedCount` | integer (int32) |  |
| `orderSettlements[].completedAmount` | Amount |  |
| `orderSettlements[].completedAmount.currencyCode` | string |  |
| `orderSettlements[].completedAmount.currency` | string | ISO 4217 currency code |
| `orderSettlements[].completedAmount.decimals` | integer (int32) |  |
| `orderSettlements[].completedAmount.value` | integer (int64) |  |
| `orderSettlements[].completedAmount.valueForView` | number (double) |  |
| `orderSettlements[].completedAmount.money` | Money |  |
| `orderSettlements[].refundedAmount` | Amount |  |
| `orderSettlements[].refundedAmount.currencyCode` | string |  |
| `orderSettlements[].refundedAmount.currency` | string | ISO 4217 currency code |
| `orderSettlements[].refundedAmount.decimals` | integer (int32) |  |
| `orderSettlements[].refundedAmount.value` | integer (int64) |  |
| `orderSettlements[].refundedAmount.valueForView` | number (double) |  |
| `orderSettlements[].refundedAmount.money` | Money |  |
| `metadata` | Metadata |  |
| `metadata.pageNumber` | integer (int32) |  |
| `metadata.pageSize` | integer (int32) |  |
| `metadata.totalItems` | integer (int32) |  |
| `metadata.totalPages` | integer (int32) |  |

**Example**

```json
{
  "orderSettlements": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "createdDate": "2026-10-18T09:00:00Z",
      "modifiedDate": "2026-10-18T09:00:00Z",
      "version": 0,
      "erasedAt": "2026-10-18T09:00:00Z",
      "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "merchantName": "string",
      "currency": "SEK",
      "preparedDate": "2026-10-18T09:00:00Z",
      "payoutRequestedDate": "2026-10-18T09:00:00Z",
      "payoutCompletedDate": "2026-10-18T09:00:00Z",
      "readThroughAccountBalancingDate": "2026-10-18T09:00:00Z",
      "reference": "string",
      "settlementNumber": "string",
      "ocr": "string",
      "orderDates": {
        "startDate": "2026-10-18",
        "endDate": "2026-10-18",
        "areSame": false
      },
      "isCredit": false,
      "settlementInfo": {
        "settlementDate": "2026-10-18T09:00:00Z",
        "settledDate": "2026-10-18T09:00:00Z",
        "isSettled": false,
        "isScheduled": false,
        "ledger": {
          "currency": "SEK",
          "balance": {
            "currencyCode": "string",
            "currency": "SEK",
            "decimals": 0,
            "value": 0,
            "valueForView": 0,
            "money": {
              "decimals": 0,
              "value": 0,
              "valueForView": 0
            }
          },
          "transactions": [
            {
              "description": "string",
              "amount": {
                "currencyCode": "string",
                "currency": "SEK",
                "decimals": 0,
                "value": 0,
                "valueForView": 0,
                "money": {
                  "decimals": 0,
                  "value": 0,
                  "valueForView": 0
                }
              },
              "date": "2026-10-18T09:00:00Z",
              "type": 1,
              "balance": {
                "currencyCode": "string",
                "currency": "SEK",
                "decimals": 0,
                "value": 0,
                "valueForView": 0,
                "money": {
                  "decimals": 0,
                  "value": 0,
                  "valueForView": 0
                }
              },
              "reference": {
                "value": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
                "type": 1
              },
              "isPending": false,
              "messageKey": "string",
              "messageArgs": {
                "key": "string"
              }
            }
          ]
        },
        "canSchedule": false,
        "canReschedule": false,
        "canSettle": false,
        "canCancel": false,
        "canCredit": false
      },
      "transferInfo": {
        "transfers": [
          {
            "transferId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "externalId": "string",
            "transferAmount": {
              "currencyCode": "string",
              "currency": "SEK",
              "decimals": 0,
              "value": 0,
              "valueForView": 0,
              "money": {
                "decimals": 0,
                "value": 0,
                "valueForView": 0
              }
            },
            "transferStatus": 1,
            "balanceAccountId": "string",
            "counterparty": "string",
            "balanceAccountDescription": "string",
            "counterpartyDescription": "string",
            "direction": 1,
            "category": 1,
            "type": 1,
            "reason": 1,
            "creationDate": "2026-10-18T09:00:00Z",
            "description": "string"
          }
        ],
        "pendingAcknowledgmentTransferId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
      },
      "sourceBalanceAccountId": "string",
      "totalAmount": {
        "currencyCode": "string",
        "currency": "SEK",
        "decimals": 0,
        "value": 0,
        "valueForView": 0,
        "money": {
          "decimals": 0,
          "value": 0,
          "valueForView": 0
        }
      },
      "completedCount": 0,
      "refundedCount": 0,
      "completedAmount": {
        "currencyCode": "string",
        "currency": "SEK",
        "decimals": 0,
        "value": 0,
        "valueForView": 0,
        "money": {
          "decimals": 0,
          "value": 0,
          "valueForView": 0
        }
      },
      "refundedAmount": {
        "currencyCode": "string",
        "currency": "SEK",
        "decimals": 0,
        "value": 0,
        "valueForView": 0,
        "money": {
          "decimals": 0,
          "value": 0,
          "valueForView": 0
        }
      }
    }
  ],
  "metadata": {
    "pageNumber": 0,
    "pageSize": 0,
    "totalItems": 0,
    "totalPages": 0
  }
}
```

### 400

`pageNumber` or `pageSize` is not a number: the validation problem, with `code` `request_invalid`.

Error codes: [request_invalid](https://developers.rivr.io/errors/request_invalid.md)

`application/json`

```json
{
  "type": "string",
  "title": "string",
  "status": 400,
  "detail": "string",
  "instance": "string",
  "errors": {
    "key": [
      "string"
    ]
  },
  "code": "string",
  "message": "string"
}
```

### 401

The token is missing (`token_missing`), not valid (`token_invalid`), expired (`token_expired`) or could not be
checked (`authentication_unavailable`), or it is not issued for a merchant (`merchant_token_required`).

Error codes: [token_missing](https://developers.rivr.io/errors/token_missing.md), [token_invalid](https://developers.rivr.io/errors/token_invalid.md), [token_expired](https://developers.rivr.io/errors/token_expired.md), [authentication_unavailable](https://developers.rivr.io/errors/authentication_unavailable.md), [merchant_token_required](https://developers.rivr.io/errors/merchant_token_required.md)

`application/json`

```json
{
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid Authorization Header",
  "propertyName": null,
  "message": "The request has no valid Authorization header. Send the token in the Authorization header, after Bearer.",
  "errorCode": "token_missing",
  "code": "token_missing",
  "type": "https://developers.rivr.io/errors/token_missing"
}
```

### 403

The token lacks the scope (`invalid_scope`) or is a rivr-auth token that is not a clinic token
(`clinic_token_required`). The body also carries `error` and `error_description`, as before.

Error codes: [invalid_scope](https://developers.rivr.io/errors/invalid_scope.md), [clinic_token_required](https://developers.rivr.io/errors/clinic_token_required.md)

`application/json`

```json
{
  "error": "invalid_scope",
  "error_description": "The scope(s) 'public:order-settlements:read' is required.",
  "propertyName": null,
  "message": "The scope(s) 'public:order-settlements:read' is required.",
  "errorCode": "invalid_scope",
  "code": "invalid_scope",
  "type": "https://developers.rivr.io/errors/invalid_scope"
}
```

### 500

Something unexpected failed: `internal_error`.

Error codes: [internal_error](https://developers.rivr.io/errors/internal_error.md)

`application/json`

```json
{
  "propertyName": null,
  "message": "Something unexpected failed at Rivr, and whether the request was carried out is not known. Check the order or what the request was about before you retry.",
  "errorCode": "internal_error",
  "code": "internal_error",
  "type": "https://developers.rivr.io/errors/internal_error"
}
```

## Example request

```bash
curl -X GET https://api.test.rivr.io/api/public/order-settlements \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```