# Account Balances
URL: https://www.quiltt.dev/api/balances
Description: Learn how to fetch and refresh Account Balances through Quiltt
Navigation: api → balances
Tags: API, Core Resources

A **Balance** in Quiltt represents the amount of money currently available on a specific [Account](/api/accounts). Account Balances are typically updated automatically as part of the regular Connection sync flow.

For payment-related use-cases, you can also [trigger a real-time balance refresh](#triggering-a-real-time-balance-refresh) to have the underlying provider fetch the latest data from the connected institution. You can see how the real-time balance feature works in the video below:

[Video]

Warning:
Note that in Production, triggering real-time balance checks will usually incur a small fee per API call. Please refer to your Quiltt agreement for more information.

## Schemas & Types

Profile GraphQL Note:

## GraphQL Queries

Profile GraphQL Note:

Balances are available on all Accounts in Quiltt. For example, we can fetch the latest balance for all accounts on a profile with the below query:

GraphQLRequest:

Query:
```graphql
query {
  accounts {
    id
    name
    balance [id
      at
      available
      current
      limit]
  }
}
```

  

Response:
```json
{
  "data": {
    "accounts": [
      {
        "id": "acct_12sf19AeKaWfukStXAL7nN",
        "name": "Premium Checking",
        "balance": ["id": "bal_12v6sGb87FS28QIGWVgnnm",
          "at": "2024-06-09T07:40:20Z",
          "available": null,
          "current": 3141.59,
          "limit": null]
      },
      {
        "id": "acct_12vAFU1c4t514E40Nb9NTW",
        "name": "Premium Credit Card",
        "balance": ["id": "bal_12vbv96FYbSi0EP4H7hgVt",
          "at": "2024-06-01T18:55:35Z",
          "available": 12665.66,
          "current": -2134.34,
          "limit": -15000.00]
      },
    ]
  }
}
```

### Balance Values by Account Type

Quiltt normalizes balance values across providers so that the sign convention is consistent regardless of the upstream source.

**Asset accounts** (checking, savings, investment): a positive balance indicates money in the account, a negative balance indicates the account holder owing the institution.

**Liability accounts** (credit cards, loans): a negative balance indicates the amount owed, a positive amount indicates the lender owing the account holder.

For example, a credit card balance of `-2134.34` means you owe **$2,134.34**.

## REST Operations

### Trigger a Balance Refresh

API Endpoint - POST https://api.quiltt.io/v1/accounts/{accountId}/balances/refresh:

You can trigger a real-time balance refresh by calling the [Trigger a Balance Refresh](/api-reference/rest#tag/Balances) REST endpoint.

Code Examples:

  ```sh
    curl --request POST \
      --url 'https://api.quiltt.io/v1/accounts/acct_12wm3n4PaWHdcMgu6ZVDx5/balances/refresh' \
      --header 'Authorization: Bearer <API_SECRET_KEY>'
    ```
  ```http
    202 Accepted
    ```

Successful requests will return a `202 Accepted` status code and trigger a refresh from the underlying provider. As soon as new balance information is available, Quiltt will fire the `balance.created` event with the new balance data.

Events triggered by real-time balance refreshes can be identified by checking the `source` field, which will be set to `"REFRESH"`.

## Webhooks

Balance Schema:

### `balance.created`

You can subscribe to new balance data by listening to the `balance.created` webhook. This event fires anytime new balance information is obtained for an Account.

The webhook will include the `balance.created` event type and the new Balance information:

```json
{
  "id": "evt_12wkam1rFDQg0m8OLObJM1",
  "at": "2026-01-02T05:42:41Z",
  "type": "balance.created",
  "profile": ["id": "p_12uGLpPexyTkZCcJJntSjb",
    "uuid": "018a72f8-5434-7262-a029-a186fb0c5f33",
    "metadata": null],
  "record": ["id": "bal_12wm3nAz3ZSpYWxauhLqrf",
    "accountId": "acct_12wm3n4PaWHdcMgu6ZVDx5",
    "at": "2024-06-07T08:27:37Z",
    "source": "REFRESH",
    "available": 100.0,
    "current": 110.0,
    "limit": null,],
  "metadata": {}
}
```

Webhooks Note: