# GET /api/public/order-settlements/{orderSettlementId}

> Retrieve Order Settlement

- Surface: `/api/public` · operationId `getOrderSettlement` · 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/getOrderSettlement

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

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `orderSettlementId` | path | string (uuid) | yes | The identifier of the order settlement to retrieve. |

## Responses

### 200

OK

`application/json`

**Response fields**

| Field | Type | Description |
| --- | --- | --- |
| `id` | string (uuid) |  |
| `createdDate` | string (date-time) |  |
| `modifiedDate` | string (date-time) |  |
| `version` | integer (int32) | (nullable) |
| `merchantId` | string (uuid) |  |
| `merchantName` | string | (nullable) |
| `preparedDate` | string (date-time) | (nullable) |
| `payoutRequestedDate` | string (date-time) | (nullable) |
| `payoutCompletedDate` | string (date-time) | (nullable) |
| `readThroughAccountBalancingDate` | string (date-time) | (nullable) |
| `reference` | string | (nullable) |
| `settlementNumber` | string | (nullable) |
| `ordersByPaymentMethod` | OrdersByPaymentMethod[] |  |
| `ordersByPaymentMethod[].paymentMethod` | PaymentMethod | (Values: 0 = NotPaid, 1 = Giro, 2 = InstalmentDefault, 4 = InstalmentInterestFree, 8 = InstalmentFullKyc, 14 = Instalment, 16 = Direct, 64 = Swish, 128 = Invoice, 256 = Card, 512 = DigitalWallet, 1024 = AvardaInvoice, … and 10 more) Full list: the schema [PaymentMethod](https://developers.rivr.io/openapi/api-public.json#/components/schemas/PaymentMethod) |
| `ordersByPaymentMethod[].totalAmount` | number (double) |  |
| `ordersByPaymentMethod[].completedAmount` | number (double) |  |
| `ordersByPaymentMethod[].refundedAmount` | number (double) |  |
| `ordersByPaymentMethod[].completedCount` | integer (int32) |  |
| `ordersByPaymentMethod[].refundedCount` | integer (int32) |  |
| `ordersByPaymentMethod[].orders` | OrderSettlementOrder[] |  |
| `ordersByPaymentMethod[].orders[].orderId` | string (uuid) |  |
| `ordersByPaymentMethod[].orders[].orderNumber` | string | (nullable) |
| `ordersByPaymentMethod[].orders[].createdDate` | string (date-time) |  |
| `ordersByPaymentMethod[].orders[].description` | string | (nullable) |
| `ordersByPaymentMethod[].orders[].totalAmountInclVat` | number (double) |  |
| `ordersByPaymentMethod[].orders[].totalAmountExclVat` | number (double) |  |
| `ordersByPaymentMethod[].orders[].vatPercentage` | number (double) |  |
| `ordersByPaymentMethod[].orders[].paymentMethod` | PaymentMethod | (Values: 0 = NotPaid, 1 = Giro, 2 = InstalmentDefault, 4 = InstalmentInterestFree, 8 = InstalmentFullKyc, 14 = Instalment, 16 = Direct, 64 = Swish, 128 = Invoice, 256 = Card, 512 = DigitalWallet, 1024 = AvardaInvoice, … and 10 more) Full list: the schema [PaymentMethod](https://developers.rivr.io/openapi/api-public.json#/components/schemas/PaymentMethod) |
| `ordersByPaymentMethod[].orders[].reference` | string | (nullable) |
| `ordersByPaymentMethod[].orders[].metadata` | map<string, string> |  |
| `ordersByPaymentMethod[].orders[].kind` | string | The row's kind (optional). `"SoldClaim"` for a sold-claim row: the amount is the clinic's net for a receivable Rivr has sold, not a payment of the order by the patient. The order's own invoice is then paid only in part; the rest is the clinic's credit loss. Left out of the JSON for an ordinary row. (nullable) |
| `ordersByPaymentMethod[].refundedOrders` | OrderSettlementOrder[] |  |
| `ordersByPaymentMethod[].refundedOrders[].orderId` | string (uuid) |  |
| `ordersByPaymentMethod[].refundedOrders[].orderNumber` | string | (nullable) |
| `ordersByPaymentMethod[].refundedOrders[].createdDate` | string (date-time) |  |
| `ordersByPaymentMethod[].refundedOrders[].description` | string | (nullable) |
| `ordersByPaymentMethod[].refundedOrders[].totalAmountInclVat` | number (double) |  |
| `ordersByPaymentMethod[].refundedOrders[].totalAmountExclVat` | number (double) |  |
| `ordersByPaymentMethod[].refundedOrders[].vatPercentage` | number (double) |  |
| `ordersByPaymentMethod[].refundedOrders[].paymentMethod` | PaymentMethod | (Values: 0 = NotPaid, 1 = Giro, 2 = InstalmentDefault, 4 = InstalmentInterestFree, 8 = InstalmentFullKyc, 14 = Instalment, 16 = Direct, 64 = Swish, 128 = Invoice, 256 = Card, 512 = DigitalWallet, 1024 = AvardaInvoice, … and 10 more) Full list: the schema [PaymentMethod](https://developers.rivr.io/openapi/api-public.json#/components/schemas/PaymentMethod) |
| `ordersByPaymentMethod[].refundedOrders[].reference` | string | (nullable) |
| `ordersByPaymentMethod[].refundedOrders[].metadata` | map<string, string> |  |
| `ordersByPaymentMethod[].refundedOrders[].kind` | string | The row's kind (optional). `"SoldClaim"` for a sold-claim row: the amount is the clinic's net for a receivable Rivr has sold, not a payment of the order by the patient. The order's own invoice is then paid only in part; the rest is the clinic's credit loss. Left out of the JSON for an ordinary row. (nullable) |
| `ocr` | string | (nullable) |
| `isCredit` | boolean |  |
| `totalAmount` | number (double) |  |
| `completedCount` | integer (int32) |  |
| `refundedCount` | integer (int32) |  |
| `completedAmount` | number (double) |  |
| `refundedAmount` | number (double) |  |
| `settlementInfo` | PublicApiSettlementInfo |  |
| `settlementInfo.settlementDate` | string (date-time) | (nullable) |
| `settlementInfo.settledDate` | string (date-time) | (nullable) |
| `settlementInfo.isSettled` | boolean |  |
| `settlementInfo.isScheduled` | boolean |  |
| `settlementInfo.ledger` | Ledger |  |
| `settlementInfo.ledger.currency` | string | ISO 4217 currency code |
| `settlementInfo.ledger.balance` | Amount |  |
| `settlementInfo.ledger.transactions` | Transaction[] |  |
| `settlementInfo.canSchedule` | boolean |  |
| `settlementInfo.canReschedule` | boolean |  |
| `settlementInfo.canSettle` | boolean |  |
| `settlementInfo.canCancel` | boolean |  |
| `settlementInfo.canCredit` | boolean |  |
| `transferInfo` | EntityTransferInfo |  |
| `transferInfo.transfers` | EntityTransfer[] |  |
| `transferInfo.transfers[].transferId` | string (uuid) |  |
| `transferInfo.transfers[].externalId` | string |  |
| `transferInfo.transfers[].transferAmount` | Amount |  |
| `transferInfo.transfers[].transferStatus` | TransferStatus | (Values: 1 = ApprovalPending, 2 = AtmWithdrawal, 3 = AtmWithdrawalReversalPending, 4 = AtmWithdrawalReversed, 5 = AuthAdjustmentAuthorised, 6 = AuthAdjustmentError, 7 = AuthAdjustmentRefused, 8 = Authorised, 9 = BankTransfer, 10 = BankTransferPending, 11 = Booked, 12 = BookingPending, … and 53 more) Full list: the schema [TransferStatus](https://developers.rivr.io/openapi/api-public.json#/components/schemas/TransferStatus) |
| `transferInfo.transfers[].balanceAccountId` | string |  |
| `transferInfo.transfers[].counterparty` | string |  |
| `transferInfo.transfers[].balanceAccountDescription` | string | (nullable) |
| `transferInfo.transfers[].counterpartyDescription` | string | (nullable) |
| `transferInfo.transfers[].direction` | TransferDirection | (Values: 1 = Incoming, 2 = Outgoing) |
| `transferInfo.transfers[].category` | TransferCategory | (Values: 1 = Bank, 2 = Internal, 3 = IssuedCard, 4 = PlatformPayment) |
| `transferInfo.transfers[].type` | TransferType | (Values: 1 = AtmWithdrawal, 2 = AtmWithdrawalReversal, 3 = BalanceAdjustment, 4 = BalanceMigration, 5 = BalanceRollover, 6 = BankTransfer, 7 = Capture, 8 = CaptureReversal, 9 = CardTransfer, 10 = CashOutFee, 11 = CashOutFunding, 12 = CashOutInstruction, … and 26 more) Full list: the schema [TransferType](https://developers.rivr.io/openapi/api-public.json#/components/schemas/TransferType) |
| `transferInfo.transfers[].reason` | TransferReason | (Values: 1 = AmountLimitExceeded, 2 = Approved, 3 = BalanceAccountTemporarilyBlockedByTransactionRule, 4 = CounterpartyAccountBlocked, 5 = CounterpartyAccountClosed, 6 = CounterpartyAccountNotFound, 7 = CounterpartyAddressRequired, 8 = CounterpartyBankTimedOut, 9 = CounterpartyBankUnavailable, 10 = DeclinedByTransactionRule, 11 = Error, 12 = NotEnoughBalance, … and 4 more) Full list: the schema [TransferReason](https://developers.rivr.io/openapi/api-public.json#/components/schemas/TransferReason) |
| `transferInfo.transfers[].creationDate` | string (date-time) | (nullable) |
| `transferInfo.transfers[].description` | string | (nullable) |
| `transferInfo.pendingAcknowledgmentTransferId` | string (uuid) | (nullable) |

**Example**

```json
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdDate": "2026-10-18T09:00:00Z",
  "modifiedDate": "2026-10-18T09:00:00Z",
  "version": 0,
  "merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "merchantName": "string",
  "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",
  "ordersByPaymentMethod": [
    {
      "paymentMethod": 1,
      "totalAmount": 0,
      "completedAmount": 0,
      "refundedAmount": 0,
      "completedCount": 0,
      "refundedCount": 0,
      "orders": [
        {
          "orderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "orderNumber": "string",
          "createdDate": "2026-10-18T09:00:00Z",
          "description": "string",
          "totalAmountInclVat": 0,
          "totalAmountExclVat": 0,
          "vatPercentage": 0,
          "paymentMethod": 1,
          "reference": "string",
          "metadata": {
            "key": "string"
          },
          "kind": "string"
        }
      ],
      "refundedOrders": [
        {
          "orderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
          "orderNumber": "string",
          "createdDate": "2026-10-18T09:00:00Z",
          "description": "string",
          "totalAmountInclVat": 0,
          "totalAmountExclVat": 0,
          "vatPercentage": 0,
          "paymentMethod": 1,
          "reference": "string",
          "metadata": {
            "key": "string"
          },
          "kind": "string"
        }
      ]
    }
  ],
  "ocr": "string",
  "isCredit": false,
  "totalAmount": 0,
  "completedCount": 0,
  "refundedCount": 0,
  "completedAmount": 0,
  "refundedAmount": 0,
  "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"
  }
}
```

### 204

There is no order settlement with this id for the merchant.

### 400

The id is not a UUID: 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`), is a rivr-auth token that is not a clinic token
(`clinic_token_required`), or the order settlement belongs to another merchant on the same platform
(`merchant_mismatch`). 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), [merchant_mismatch](https://developers.rivr.io/errors/merchant_mismatch.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/88889999-aaaa-bbbb-cccc-ddddeeeeffff \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```