Account Balances
Loading...
Loading...
Loading...
A Balance in Quiltt represents the amount of money currently available on a specific Account. 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 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:
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.
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:
query {
accounts {
id
name
balances {
id
at
available
current
limit
}
}
}
{
"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
}
},
]
}
}
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.
POSThttps://api.quiltt.io/v1/accounts/{accountId}/balances/refreshCopy endpoint URL to clipboardYou can trigger a real-time balance refresh by calling the Trigger a Balance Refresh REST endpoint.
curl --request POST \
--url 'https://api.quiltt.io/v1/accounts/acct_12wm3n4PaWHdcMgu6ZVDx5/balances/refresh' \
--header 'Authorization: Bearer <API_SECRET_KEY>'
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".
Represents an Account Balance.
id:string<global_id-v1>requiredThe ID of the Balance.
accountId:string<global_id-v1>requiredThe ID of the Account.
at:string<date-time>requiredThe timestamp of the Account Balance record.
source:stringrequiredThe source of the Balance data.
Note that this enum is extensible and new values may be added over time.
INITIAL - Initial value from the provider.SYNC - Regular sync with the provider.REFRESH - Provider response from a triggered Refresh Balance call.INITIAL SYNC REFRESH available:number<double> | nullrequiredThe amount of funds accounting for pending Transactions. For asset accounts (checking, savings, investment), a positive balance indicates money in the account and a negative balance indicates the account holder owing the institution. For liability accounts (credit cards, loans), a negative balance indicates the amount owed and a positive amount indicates the lender owing the account holder.
current:number<double> | nullrequiredThe amount of funds based on posted Transactions. For asset accounts (checking, savings, investment), a positive balance indicates money in the account and a negative balance indicates the account holder owing the institution. For liability accounts (credit cards, loans), a negative balance indicates the amount owed and a positive amount indicates the lender owing the account holder.
limit:number<double> | nullrequiredThe amount of funds that may be overdraft or spent on credit.
balance.createdYou 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:
{
"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": {}
}