---
title: "Get settlement rules"
method: GET
path: "/virtual-accounts/{accountId}/settlement-rules"
tags: ["Settlement Accounts"]
---

# Get settlement rules

`GET /virtual-accounts/{accountId}/settlement-rules`

## Request

- Base URL: `https://api.token.io`
- URL: `https://api.token.io/virtual-accounts/{accountId}/settlement-rules`
- Auth: one of:
  - HTTP bearer
  - API key in header `Authorization`

The `GET /virtual-accounts/{accountId}/settlement-rules` endpoint retrieves information about settlement rules, for a given settlement account, according to the settlement rule status in the request. If no status is provided, the endpoint retrieves all settlement rules for the settlement account.

## Path parameters

- `accountId` string, required

## Request body

- GetVirtualAccountSettlementRulesRequest: Contains the request payload to get settlement rules.
  - `accountId` string: The settlement account id.
  - `status` 'ACTIVE' | 'INACTIVE': The status of the settlement rule.

## Response `200`

Successful response

- GetVirtualAccountSettlementRulesResponse: Contains the response of the get settlement rules request.
  - `settlementRule` SettlementRule[]
    - `id` string, uuid: The id of the settlement rule.
    - `payerAccountId` string: The id of the payer settlement account.
    - `payeeAccountDetails` Creditor
      - `name` string: The owner name for the creditor account.
      - `ultimateCreditorName` string: The ultimate creditor name.
      - `bankName` string: The creditor's bank name.
      - `accountNumber` string: The unique identifier for the bank account in the UK or Ireland.
      - `bic` string: The Business Identifier Code (BIC), <a href="https://www.iso.org/standard/84108.html" target="_blank">ISO 9362</a>, is the SWIFT Address assigned to a bank in order to send automated payments quickly and accurately to the banks concerned. It uniquely identifies the name and country, (and sometimes the branch) of the bank involved. BICs are often called SWIFT Codes and can be either 8 or 11 characters long."
      - `iban` string: The International Bank Account Number, used when sending interbank transfers or wiring money from one bank to another, especially across international borders. It consists of a two-letter country code followed by two check digits and up to thirty-five alphanumeric characters.
      - `sortCode` string: The number assigned to a branch of a bank, typically containing six digits and most commonly used in the UK and Ireland.
    - `amountType` 'FIXED_VALUE' | 'PERCENTAGE' | 'BALANCE_TO_RETAIN' | 'PREVIOUS_DAY_TOTAL': The type of the amount.
    - `amountValue` string: The value of the amount.
    - `effectiveFrom` string: The start date of the settlement rule is formatted as `YYYY-MM-DD` if the time interval is not INTRADAY. Otherwise, it is formatted as `YYYY-MM-DDTHH:MM:SSZ`.
    - `effectiveTo` string: The end date of the settlement rule is formatted as `YYYY-MM-DD` if the time interval is not INTRADAY. Otherwise, it is formatted as `YYYY-MM-DDTHH:MM:SSZ`.
    - `timeInterval` 'INTRADAY' | 'DAILY' | 'WEEKLY' | 'MONTHLY' | 'QUARTERLY' | 'HALF_YEARLY' | 'YEARLY': The time interval.
    - `intradayIntervalHours` integer: The intraday interval hours.
    - `intradayIntervalMinutes` integer: The intraday interval minutes.
    - `onBehalfOfId` string: The id of the ultimate client on whose behalf the account is created. If the account is created on behalf of a sub-TPP, this field will contain the sub-TPP `referenceId`. This field is mandatory for unregulated TPPs.
    - `description` string: The description used for payouts created due to this rule. The maximum length is 18 characters and allowed characters are alphanumeric, space, hyphen (-), period (.), ampersand (&), and forward slash (/). The minimum length is 6 characters. **NOTE**: When enableDynamicRef is true the maximum length is 9 characters.
    - `status` 'ACTIVE' | 'INACTIVE': The status of the settlement rule.
    - `enableDynamicRef` boolean: Controls how the reference is generated for a payout created as the result of a triggered settlement rule. When set to true, the payment reference is automatically generated by combining "description" with the current date, separated by a hyphen, in the format "{description}-{DDMMYYYY}," where DDMMYYYY is the zero-padded date the payout was created (e.g. 01082026 for 1 August 2026)

## Other responses

- `400`: The client specified an invalid argument
- `401`: The authorization information is missing or invalid
- `403`: Permission to access this endpoint is denied
- `429`: Too many requests
- `500`: An unexpected or internal server error
- `501`: The operation was not implemented
- `503`: Service is unavailable
- `504`: Gateway has timed out

## Changes

- **2026-09-17** `4e8c473aff5c`: 2 warning, 5 info
  - removed the optional property `settlementRule/items/settlementRuleId` from the response with the `200` status
  - added the new `PREVIOUS_DAY_TOTAL` enum value to the `settlementRule/items/amountType` response property for the response status `200`
  - added the optional property `settlementRule/items/enableDynamicRef` to the response with the `200` status
  - added the optional property `settlementRule/items/id` to the response with the `200` status
  - …3 more

[Operation history](https://skmtc.dev/token/apis/token-io-s-open-banking-api-for-tpps/changes/virtual-accounts/:accountId/settlement-rules/get.md)

---

[API](https://skmtc.dev/token/apis/token-io-s-open-banking-api-for-tpps.md) - [All operations](https://skmtc.dev/token/apis/token-io-s-open-banking-api-for-tpps/llms.txt) - [OpenAPI document](https://skmtc.dev/token/apis/token-io-s-open-banking-api-for-tpps/revisions/f705d3537678?raw)