> ## 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.

# AUD Balance API Reference

> Query AUD account balances (available, incoming, outgoing, rolling reserve, and withdrawable) and retrieve balance history via the Hello Clever v1 API.

The Balance endpoints give you real-time visibility into your Hello Clever account funds. Use the balance details endpoint to see a current snapshot across all balance types, and the balance history endpoint to audit how your balance has changed over a specified period, including payments received, refunds issued, and top-ups.

<Note>
  These endpoints support **AUD balances only**. To query balances or balance history in any other currency, use the [v2 Balance API](/api/v2/balance), which covers every currency configured on your account.
</Note>

***

## Get balance details

<Note>
  `GET /v1/balances/detail`
</Note>

Retrieve a real-time breakdown of all balance types in your account.

### Balance types

| Balance type              | Description                                                                                                                    |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `available_balance`       | Funds immediately available for transactions.                                                                                  |
| `incoming_balance`        | Funds credited from successful payments but not yet settled by the third-party provider (e.g. card processor).                 |
| `outgoing_balance`        | Funds set aside to process pending actions such as refunds, disputes, or payouts.                                              |
| `rolling_reserve_balance` | Reserved funds held as a security buffer against chargebacks or liabilities. Contact technical support to enable this feature. |
| `withdrawable_balance`    | The portion of your available balance that can be withdrawn (excludes rolling reserve funds).                                  |

### Response fields

<ResponseField name="currency" type="string">
  Currency code (`AUD`).
</ResponseField>

<ResponseField name="available_balance" type="number">
  Funds available immediately for any transaction, in AUD.
</ResponseField>

<ResponseField name="incoming_balance" type="number">
  Funds pending credit from successful payments, in AUD.
</ResponseField>

<ResponseField name="outgoing_balance" type="number">
  Funds reserved for pending refunds, disputes, or payouts, in AUD.
</ResponseField>

<ResponseField name="rolling_reserve_balance" type="number">
  Reserved funds held as a security buffer, in AUD.
</ResponseField>

<ResponseField name="withdrawable_balance" type="number">
  Available balance excluding rolling reserve funds, in AUD.
</ResponseField>

<ResponseField name="retrieved_at" type="string">
  ISO 8601 timestamp of when the balance snapshot was taken.
</ResponseField>

### Code example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url https://api-merchant.helloclever.co/api/v1/balances/detail \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```
</CodeGroup>

<CodeGroup>
  ```json 200 - Success theme={null}
  {
    "currency": "AUD",
    "available_balance": 12450.75,
    "incoming_balance": 3200.00,
    "outgoing_balance": 500.00,
    "rolling_reserve_balance": 1000.00,
    "withdrawable_balance": 11450.75,
    "retrieved_at": "2026-04-17T10:00:00Z"
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid app-id or secret-key."
  }
  ```
</CodeGroup>

***

## Get balance history

<Note>
  `GET /v1/balances/history`
</Note>

Access a detailed history of all balance changes within a specified date range. This includes incoming payments, refunds, top-ups, payouts, and any other activity that affects your account balance.

<Tip>
  For multi-currency balance history, use [`GET /v2/balances/history`](/api/v2/balance#get-balance-history) instead. It returns records across every currency on your account and includes a per-transaction fee breakdown. See [migrating from v1 balance history](/api/v2/balance#migrating-from-v1-balance-history) for the parameter and response differences.
</Tip>

### Query parameters

<ParamField query="from_date" type="string" required>
  Start of the date range in ISO 8601 format (e.g. `2026-01-01`).
</ParamField>

<ParamField query="to_date" type="string" required>
  End of the date range in ISO 8601 format (e.g. `2026-04-17`).
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number for paginated results.
</ParamField>

<ParamField query="per_page" type="number" default="20">
  Number of records per page.
</ParamField>

### Response fields

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

  <Expandable title="properties">
    <ResponseField name="id" type="string">Unique identifier for the balance history entry.</ResponseField>

    <ResponseField name="type" type="string">
      Type of balance change (e.g. `payment_received`, `refund_issued`, `top_up`, `payout`).
    </ResponseField>

    <ResponseField name="amount" type="number">
      Amount of the balance change in AUD. Positive values indicate credits; negative values indicate debits.
    </ResponseField>

    <ResponseField name="balance_after" type="number">
      Available balance after this transaction, in AUD.
    </ResponseField>

    <ResponseField name="reference_id" type="string">
      Identifier of the associated transaction (e.g. payment request ID or payout ID).
    </ResponseField>

    <ResponseField name="description" type="string">
      Human-readable description of the balance change.
    </ResponseField>

    <ResponseField name="created_at" type="string">
      ISO 8601 timestamp of when the balance change occurred.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="number">
  Total number of balance history entries matching the query.
</ResponseField>

<ResponseField name="page" type="number">
  Current page number.
</ResponseField>

### Code example

<CodeGroup>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api-merchant.helloclever.co/api/v1/balances/history?from_date=2026-04-01&to_date=2026-04-17&page=1' \
    --header 'app-id: YOUR_APP_ID' \
    --header 'secret-key: YOUR_SECRET_KEY'
  ```
</CodeGroup>

<CodeGroup>
  ```json 200 - Success theme={null}
  {
    "data": [
      {
        "id": "bh_entry_001",
        "type": "payment_received",
        "amount": 99.95,
        "balance_after": 12450.75,
        "reference_id": "pr_abc123",
        "description": "Payment received for Order #1042",
        "created_at": "2026-04-17T10:15:00Z"
      },
      {
        "id": "bh_entry_002",
        "type": "refund_issued",
        "amount": -250.00,
        "balance_after": 12200.75,
        "reference_id": "ref_jkl012",
        "description": "Refund issued for Invoice #5021",
        "created_at": "2026-04-17T11:00:00Z"
      }
    ],
    "total": 2,
    "page": 1
  }
  ```

  ```json 422 - Unprocessable Entity theme={null}
  {
    "error": "UnprocessableEntity",
    "message": "from_date and to_date are required."
  }
  ```
</CodeGroup>


## Related topics

- [Balance API Reference](/api/v2/balance.md)
- [Payment APIs for AUD](/api/v1/introduction.md)
- [Simulate Deposit API Reference](/api/v1/simulate-deposit.md)