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

# Monitor Your Balances

> Read live account balances and alert when the funds available for refunds run low

Your Quidkey accounts hold real balances at the payment provider. `GET /api/v1/balances` returns those balances live, one entry per account and currency — so you can monitor how much is available and alert your team when it runs low.

The most common use case is **watching the funds available for refunds**: the account with the `refund` role holds the pool customer refunds are paid from. Poll this endpoint on a schedule and raise an alert when that balance drops below your threshold.

<CardGroup cols={2}>
  <Card title="Console" icon="browser" href="https://console.quidkey.com">
    View balances in your dashboard
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Full endpoint specification
  </Card>
</CardGroup>

## Account roles

A merchant's provider-managed accounts are each tagged with a role. Balances are returned **per account**, because a merchant can hold several — including more than one currency. A merchant with no managed accounts yet receives an empty `data` array.

| Role        | Holds                                                                                   |
| ----------- | --------------------------------------------------------------------------------------- |
| `refund`    | The pool customer refunds are paid from — **the "available for refunds" figure**        |
| `receiving` | Funds that have just landed and are still being processed (in-flight, not yet paid out) |

<Note>
  Read the `refund` row to answer "can I cover refunds right now?". The `receiving` balance is money mid-pipeline (about to be converted and paid out) — it is not spendable refund headroom.
</Note>

## Step 1: Fetch balances

Call `GET /api/v1/balances` with your access token. As a merchant you don't pass an ID — the account is resolved from your credentials.

<Note>
  Every request needs an `Authorization: Bearer <access_token>` header. See [Authentication](/guides/payment-api/concepts/authentication) to exchange your `client_id` and `client_secret` for a token.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl 'https://core.quidkey.com/api/v1/balances' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```javascript Node.js theme={null}
  const res = await fetch('https://core.quidkey.com/api/v1/balances', {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const { data } = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      'https://core.quidkey.com/api/v1/balances',
      headers={'Authorization': f'Bearer {access_token}'},
  )
  data = res.json()['data']
  ```
</CodeGroup>

A successful response lists one row per account:

```json theme={null}
{
  "success": true,
  "data": [
    { "id": "a1b2…", "currency": "GBP", "roles": ["refund"],    "balance": "1240.50" },
    { "id": "c3d4…", "currency": "GBP", "roles": ["receiving"], "balance": "5000.00" },
    { "id": "e5f6…", "currency": "EUR", "roles": ["refund"],    "balance": null }
  ]
}
```

### Response fields

| Field      | Type           | Description                                                                          |
| ---------- | -------------- | ------------------------------------------------------------------------------------ |
| `id`       | string (uuid)  | Unique identifier of the account                                                     |
| `currency` | string         | ISO 4217 currency of the account                                                     |
| `roles`    | string\[]      | Account roles (`refund`, `receiving`, …)                                             |
| `balance`  | string \| null | Live decimal balance in the account currency, or `null` when temporarily unavailable |

<Note>
  `balance` is `null` when the provider did not report a figure for that account (e.g. a freshly provisioned account, or a transient provider hiccup). `null` means "unknown right now" — it is **not** zero. Don't render it as `0`, and don't fire a low-balance alert on it.
</Note>

## Step 2: Alert on a low refund balance

Pick the `refund` row for the currency you care about and compare it against your threshold:

<CodeGroup>
  ```javascript Node.js theme={null}
  const res = await fetch('https://core.quidkey.com/api/v1/balances', {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const { data } = await res.json();

  const THRESHOLD = 500; // GBP
  const refundGbp = data.find(b => b.currency === 'GBP' && b.roles.includes('refund'));

  if (refundGbp && refundGbp.balance !== null && Number(refundGbp.balance) < THRESHOLD) {
    await notifyOps(`Refund balance low: £${refundGbp.balance}`);
  }
  ```

  ```python Python theme={null}
  res = requests.get(
      'https://core.quidkey.com/api/v1/balances',
      headers={'Authorization': f'Bearer {access_token}'},
  )
  data = res.json()['data']

  THRESHOLD = 500.0  # GBP
  refund_gbp = next(
      (b for b in data if b['currency'] == 'GBP' and 'refund' in b['roles']),
      None,
  )

  if refund_gbp and refund_gbp['balance'] is not None and float(refund_gbp['balance']) < THRESHOLD:
      notify_ops(f"Refund balance low: £{refund_gbp['balance']}")
  ```
</CodeGroup>

<Tip>
  Balances are fetched live from the provider on every call. Poll on a sensible cadence (e.g. every few minutes) rather than on every request, and cache the result on your side if you show it in a UI.
</Tip>

## Reading another merchant's balances

Merchant credentials resolve to their own account automatically. If you are a **partner or platform** acting across merchants, name the target with `?merchant_id=`:

```
GET /api/v1/balances?merchant_id=<merchantId>
```

As a partner or platform, `merchant_id` is **required** — omitting it returns `400 MERCHANT_ID_REQUIRED`. You can only read merchants you own; anything else returns `404`.

## Next steps

<CardGroup cols={2}>
  <Card title="Payout reconciliation" icon="receipt" href="/guides/payouts/overview">
    See the transactions and fees behind each payout
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Full endpoint specification
  </Card>
</CardGroup>