> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helloclever.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance API Reference

> Query multi-currency balance details and retrieve full balance transaction history across all currencies configured on your Hello Clever merchant account.

The v2 Balance API lets you query your current balance position across all currencies configured in your Hello Clever account. You can inspect five distinct balance types to understand exactly how much is available, in-flight, reserved, or ready to withdraw, and retrieve a dated history of every transaction that changed your balance.

## Balance types

| Balance type              | Description                                                                                                                    |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `available_balance`       | The balance available for all transactions.                                                                                    |
| `incoming_balance`        | Successful payments where the third-party provider has not yet settled funds (e.g., payment card transactions).                |
| `outgoing_balance`        | Funds currently being transferred, waiting to be deducted from the available balance to process refunds, disputes, or payouts. |
| `rolling_reserve_balance` | A floating reserve amount held in the merchant balance. This is not mandatory; contact Hello Clever support to enable.         |
| `withdrawable_balance`    | The amount you can withdraw, which excludes the rolling reserve.                                                               |

***

## Get Balance Details

<Badge color="green">GET</Badge> `/v2/balances/detail`

Returns the current balance breakdown for your account in a specified currency.

### Query parameters

<ParamField query="currency" type="string" required>
  ISO 4217 currency code (e.g., `AUD`, `VND`, `MYR`). Must be a currency configured in your Hello Clever account.
</ParamField>

### Response fields

<ResponseField name="currency" type="string">
  The currency of the balance.
</ResponseField>

<ResponseField name="available_balance" type="number">
  Balance available for transactions.
</ResponseField>

<ResponseField name="incoming_balance" type="number">
  Funds received but not yet settled by the third-party provider.
</ResponseField>

<ResponseField name="outgoing_balance" type="number">
  Funds in-transit for outgoing operations (refunds, payouts, disputes).
</ResponseField>

<ResponseField name="rolling_reserve_balance" type="number">
  Reserved balance amount. Returns `0` if no rolling reserve is configured.
</ResponseField>

<ResponseField name="withdrawable_balance" type="number">
  Amount you can withdraw: `available_balance` minus `rolling_reserve_balance`.
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/balances/detail?currency=AUD' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "currency": "AUD",
    "available_balance": 125000.00,
    "incoming_balance": 5000.00,
    "outgoing_balance": 2500.00,
    "rolling_reserve_balance": 10000.00,
    "withdrawable_balance": 115000.00
  }
  ```
</CodeGroup>

<Note>
  To query balances for multiple currencies, call this endpoint once per currency. Each `app-id` maps to a single currency. If you operate multiple currencies, you will have a separate `app-id` and `secret-key` for each.
</Note>

***

## Get Balance History

<Badge color="green">GET</Badge> `/v2/balances/history`

Access a detailed history of balance transactions over a specified date range. This includes every balance change on your account, including incoming payments, payouts, settlements, refunds, top-ups, withdrawals, disputes, cashback payouts, and account transfers, across **all currencies** configured on your account.

### Query parameters

<ParamField query="from_date" type="date-time" required>
  Start of the date range, in the format `YYYY-MM-DDThh:mm:ssZ`. Interpreted as UTC.
</ParamField>

<ParamField query="to_date" type="date-time" required>
  End of the date range, in the format `YYYY-MM-DDThh:mm:ssZ`. Interpreted as UTC.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor, taken from `next_cursor` in the previous response. Omit this parameter to fetch the first page.
</ParamField>

<ParamField query="size" type="integer" default="20">
  Number of records to return per page.
</ParamField>

### Response fields

<ResponseField name="from_date" type="string">
  Start of the queried date range.
</ResponseField>

<ResponseField name="to_date" type="string">
  End of the queried date range.
</ResponseField>

<ResponseField name="account_type" type="string">
  The balance model of the requesting account: `aggregated` or `dedicated`. See [managing balances and accounts](/portal/balances) for what each model means.
</ResponseField>

<ResponseField name="size" type="integer">
  Number of records returned in this page.
</ResponseField>

<ResponseField name="next_cursor" type="string">
  Cursor to pass as the `cursor` query parameter to fetch the next page. `null` when there are no more records.
</ResponseField>

<ResponseField name="has_more" type="boolean">
  Whether more records are available after this page.
</ResponseField>

<ResponseField name="records" type="array">
  List of balance history entries.

  <Expandable title="properties">
    <ResponseField name="id" type="string">Balance ID: unique identifier for this balance entry.</ResponseField>
    <ResponseField name="amount" type="number">Net amount of the transaction, after fees.</ResponseField>

    <ResponseField name="request_type" type="string">
      Direction of the balance change: `money_in` (added) or `money_out` (deducted).
    </ResponseField>

    <ResponseField name="transaction_type" type="string">
      What caused the balance change: `payment`, `payout`, `settlement`, `refund`, `topup`, `withdrawal`, `dispute`, `dispute_fee`, `cashback_payout`, `transfer_in`, or `transfer_out`.
    </ResponseField>

    <ResponseField name="currency" type="string">Currency of this entry.</ResponseField>
    <ResponseField name="payment_method" type="string">The payment method used, for example `bsb`.</ResponseField>

    <ResponseField name="status" type="string">
      Current status of the balance flow: `waiting`, `done`, or `failed`.
    </ResponseField>

    <ResponseField name="reference_id" type="string">The reference code for the underlying transaction.</ResponseField>

    <ResponseField name="balance_detail" type="object">
      Gross, net, and fee breakdown for the entry.

      <Expandable title="properties">
        <ResponseField name="outgoing" type="number">Transaction amount excluding fees.</ResponseField>
        <ResponseField name="total" type="number">Transaction amount charged, after fees.</ResponseField>
        <ResponseField name="fees" type="number">Fee charged on the transaction.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="created_at" type="string">Timestamp when the balance transaction was created (UTC).</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```bash Request theme={null}
  curl --request GET \
    --url 'https://api.cleverhub.co/api/v2/balances/history?from_date=2026-01-01T00:00:00Z&to_date=2026-01-31T00:00:00Z' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```

  ```json Response theme={null}
  {
    "from_date": "2026-01-01T00:00:00Z",
    "to_date": "2026-01-31T00:00:00Z",
    "account_type": "aggregated",
    "size": 20,
    "next_cursor": "eyJpZCI6ImJsX3BpX3duNFRXaGxYQnJaSyJ9",
    "has_more": true,
    "records": [
      {
        "id": "bl_pi_wn4TWhlXBrZK",
        "amount": 202.66,
        "request_type": "money_out",
        "transaction_type": "settlement",
        "currency": "AUD",
        "payment_method": "bsb",
        "status": "done",
        "reference_id": "BAL_cqxDHqDOSs8=--4",
        "balance_detail": {
          "outgoing": 205,
          "total": 202.66,
          "fees": 2.34
        },
        "created_at": "2026-01-01T00:00:00.000+0000"
      }
    ]
  }
  ```
</CodeGroup>

#### Status labels in the portal

The `status` values returned by this endpoint do not all match the labels shown in the Merchant Portal:

| API value | Portal label   |
| --------- | -------------- |
| `waiting` | **Processing** |
| `done`    | **Done**       |
| `failed`  | **Failed**     |

<Note>
  Map `waiting` to **Processing** if you surface these statuses in your own interface alongside the portal, or when reconciling an API response against what a colleague sees on the [balances screen](/portal/balances#transactions-table).
</Note>

### Paginating through results

This endpoint uses **cursor-based pagination**. To walk the full result set:

<Steps>
  <Step title="Request the first page">
    Call the endpoint with `from_date` and `to_date` only, and omit `cursor`.
  </Step>

  <Step title="Check `has_more`">
    If `has_more` is `false`, you have every record and `next_cursor` is `null`. Stop here.
  </Step>

  <Step title="Request the next page">
    Pass the `next_cursor` value from the previous response as the `cursor` parameter, keeping `from_date`, `to_date`, and `size` unchanged. Repeat until `has_more` is `false`.
  </Step>
</Steps>

<Warning>
  Treat `next_cursor` as an opaque token. Its contents are an implementation detail and may change. Do not parse it, construct one yourself, or store it as a durable bookmark.
</Warning>

### Migrating from v1 balance history

If you currently call `GET /v1/balances/history`, note these differences:

|                       | v1                                     | v2                                                                   |
| --------------------- | -------------------------------------- | -------------------------------------------------------------------- |
| Currency coverage     | AUD only                               | All currencies configured on your account                            |
| Pagination            | `page` + `per_page` numbers            | `cursor` + `size` (opaque cursor)                                    |
| Date parameters       | Dates (`2026-01-01`)                   | Timestamps (`2026-01-01T00:00:00Z`), UTC                             |
| Record list field     | `data`                                 | `records`                                                            |
| Amount convention     | Signed, with negative values as debits | Unsigned `amount` plus a `request_type` of `money_in` or `money_out` |
| Balance running total | `balance_after` per entry              | Not returned                                                         |
| Fee breakdown         | Not returned                           | `balance_detail.outgoing` / `total` / `fees`                         |

<Warning>
  The amount convention differs between versions. In v1, a refund appears as a negative `amount`; in v2 the same refund has a **positive** `amount` and `request_type: "money_out"`. Summing v2 amounts without checking `request_type` will overstate your net position.
</Warning>

## Understanding your balance

Use this endpoint to monitor your account health before initiating payouts or refunds:

* Check `available_balance` before creating a payout to ensure sufficient funds.
* Monitor `incoming_balance` to anticipate upcoming settlements.
* Track `outgoing_balance` to understand funds currently committed to pending operations.
* Contact [support@helloclever.co](mailto:support@helloclever.co) to configure or adjust your `rolling_reserve_balance`.


## Related topics

- [AUD Balance API Reference](/api/v1/balance.md)
- [Simulate Deposit API Reference](/api/v1/simulate-deposit.md)
- [Multi-Currency Payout API Reference](/api/v2/payout.md)