> ## Documentation Index > Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt > Use this file to discover all available pages before exploring further. # Account Balance > AccountBalance represents a time-bounded balance snapshot for a bank account, recording opening and closing booked/value figures in a specified currency alongsi AccountBalance represents a time-bounded balance snapshot for a bank account, recording opening and closing booked/value figures in a specified currency alongside the valid-from/to period window. It is produced by the financial data ingestion pipeline (connector syncs) and acts as the join anchor for all Transactions, which reference the balance period they were captured within via a foreign key. Each AccountBalance belongs to exactly one Account (and transitively to one Workspace), and includes a suite of verification fields that the reconciliation pipeline populates to flag discrepancies between the bank-reported closing figure and the computed sum of transactions. | Naming | Value | | ------------------------------- | ------------------ | | Object | Account Balance | | Resource type (JSON:API `type`) | `account_balance` | | Collection / records root | `account_balances` | | REST base | `/v1/balances` | | Entity class | `AccountBalance` | ## API operations | Operation | Method & path | Status | | --------- | -------------------------- | ------------- | | List | `GET /v1/balances` | โœ… Implemented | | Retrieve | `GET /v1/balances/{id}` | โœ… Implemented | | Create | `POST /v1/balances` | ๐ŸŸก Planned | | Update | `PATCH /v1/balances/{id}` | ๐ŸŸก Planned | | Delete | `DELETE /v1/balances/{id}` | ๐ŸŸก Planned | ## Data model ### Attributes | Field | Type | Required | Constraints | Allowed values | Description | | ------------------------------------------- | ---------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | account\_balance\_id | string, UUID | โœ… Yes | unique; defaultRaw: gen\_random\_uuid() | โ€” | Public stable identifier for this balance snapshot. Used in all API responses and external references. Never expose the internal pk. | | accounting\_balance | object (JSONB), nullable | โšช No | JSONB; all sub-fields documented below | โ€” | Bank-reported balance figures for this period. Contains four monetary fields (opening\_booked, opening\_value, closing\_booked, closing\_value) and the ISO-4217 currency code. closing\_booked and closing\_value may be null for open (current) periods. | | accounting\_balance.opening\_booked | number | โšช No | JSONB sub-field; display\_type: amount | โ€” | Booked (settled) opening balance for the period in the account's currency. | | accounting\_balance.opening\_value | number | โšช No | JSONB sub-field; display\_type: amount | โ€” | Value (including pending) opening balance for the period. | | accounting\_balance.closing\_booked | number \| null | โšช No | JSONB sub-field; display\_type: amount; null for open periods | โ€” | Booked closing balance at the end of the period. Null when balance\_at\_to is null (current open period). | | accounting\_balance.closing\_value | number \| null | โšช No | JSONB sub-field; display\_type: amount; null for open periods | โ€” | Value closing balance at the end of the period. Null when balance\_at\_to is null. | | accounting\_balance.currency | string | โšช No | JSONB sub-field; display\_type: unique\_key; ISO-4217 3-letter code | โ€” | ISO-4217 currency code for all monetary figures within this accounting\_balance object. | | foreign\_exchange | array of objects (JSONB), nullable | โšช No | JSONB array; each element has currency\_rate, currency\_pair, currency\_rate\_source, currency\_rate\_at | โ€” | Optional array of FX rate snapshots applied to this balance period. Carries the rate, the pair (e.g. EUR/USD), the source (e.g. ECB), and the timestamp of the rate. Populated by connectors that provide multi-currency balance data. | | foreign\_exchange\[].currency\_rate | number | โšช No | JSONB sub-field | โ€” | The exchange rate value for the currency pair at currency\_rate\_at. | | foreign\_exchange\[].currency\_pair | string | โšช No | JSONB sub-field | โ€” | Currency pair in ISO-4217 slash notation (e.g. EUR/USD). | | foreign\_exchange\[].currency\_rate\_source | string | โšช No | JSONB sub-field | โ€” | Source of the exchange rate (e.g. ECB, Plaid, provider-specific). | | foreign\_exchange\[].currency\_rate\_at | string (ISO-8601 timestamp) | โšช No | JSONB sub-field | โ€” | Timestamp at which the FX rate was observed or fixed. | | balance\_at\_from | string (timestamp), nullable | โšช No | columnType: timestamp; display\_type: datetime; indexed in idx\_account\_balances\_date\_range; also in partial index idx\_account\_balances\_current | โ€” | Start of the validity window for this balance snapshot. Inclusive lower bound of the period. Combined with balance\_at\_to it defines the interval. Indexed for efficient period range lookups. | | balance\_at\_to | string (timestamp), nullable | โšช No | columnType: timestamp; display\_type: datetime; indexed in idx\_account\_balances\_date\_range; null when period is still open (current balance) | โ€” | End of the validity window. Null for the current (open) balance period. The partial index idx\_account\_balances\_current targets rows WHERE balance\_at\_to IS NULL for fast current-balance lookups. | | verified\_at | string (timestamp), nullable | โšช No | columnType: timestamp | โ€” | Timestamp when the reconciliation pipeline last successfully verified this balance period (i.e. sum of transactions matched the closing\_booked figure within tolerance). | | verification\_error | boolean, nullable | โšช No | nullable boolean | true \| false \| null | Flag set by the reconciliation pipeline. True when calculated\_balance\_diff does not equal expected\_balance\_diff. Null means verification has not yet run for this period. | | verification\_error\_detail | string (text), nullable | โšช No | type: text | โ€” | Human-readable explanation of the verification failure. Populated only when verification\_error is true. Contains the discrepancy detail reported by the reconciliation pipeline. | | calculated\_balance\_diff | number (numeric), nullable | โšช No | type: numeric(10,0) โ€” integer precision, no decimal places | โ€” | The balance difference computed by the verification pipeline: sum of transaction amounts in the period minus the expected delta between opening and closing booked balances. | | expected\_balance\_diff | number (numeric), nullable | โšช No | type: numeric(10,0) โ€” integer precision, no decimal places | โ€” | The expected balance difference derived from accounting\_balance (closing\_booked minus opening\_booked). Compared against calculated\_balance\_diff to detect missing or duplicate transactions. | | verification\_last\_run\_at | string (timestamp), nullable | โšช No | columnType: timestamp | โ€” | Timestamp of the most recent reconciliation pipeline run against this balance period, regardless of outcome. Distinct from verified\_at, which is only stamped on success. | | raw\_data | unknown (JSONB), nullable | โšช No | JSONB; shape is connector-specific | โ€” | Complete provider-native payload from which this balance was derived (e.g. the full Plaid account/balance JSON response). Shape varies by connector. Preserved for audit and re-processing; not exposed in standard API responses. | | created\_at | string (timestamptz), ๐Ÿ”’ system | โœ… Yes | onCreate: () => new Date(); not null | โ€” | Timestamp when the record was first persisted. Set automatically by the MikroORM onCreate lifecycle hook. | | updated\_at | string (timestamptz), ๐Ÿ”’ system | โšช No | onCreate and onUpdate: () => new Date() | โ€” | Timestamp of the last update. Set automatically on create and every subsequent write by the MikroORM onUpdate lifecycle hook. | | deleted\_at | string (timestamptz), nullable | โšช No | nullable; soft-delete sentinel; partial index idx\_account\_balances\_current WHERE deleted\_at IS NULL | โ€” | Soft-delete timestamp. Null means the record is active. All queries must filter deleted\_at IS NULL. Also guards the partial index idx\_account\_balances\_workspace\_deleted. | ### Relationships | Name | Type | Required | Description | | ------------ | --------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | account | to-one (Account) | โšช No (nullable) | The bank account this balance snapshot belongs to. FK: account\_pk โ†’ core\_api.accounts.pk. ON UPDATE CASCADE / ON DELETE SET NULL. Indexed via idx\_account\_balances\_account. Also part of the partial index idx\_account\_balances\_current for current-balance lookups. | | workspace | to-one (Workspace) | โšช No (nullable) | Tenant scope. FK: workspace\_pk โ†’ core\_api.workspaces.pk. ON UPDATE CASCADE / ON DELETE SET NULL. Every query must filter by workspace. Indexed together with deleted\_at in idx\_account\_balances\_workspace\_deleted for Hasura permission filter hot-path. | | transactions | to-many (Transaction) | โ€” | All Transaction records that fall within this balance period. Inverse of Transaction.account\_balance (FK: transactions.account\_balance\_pk). A single AccountBalance can hold zero to many transactions. Used by composites such as composite\_total\_amount\_currency on the accounts root. | ### System-computed * account\_balance\_id: generated by PostgreSQL gen\_random\_uuid() on INSERT (defaultRaw). Unique constraint enforced at the database level. * created\_at: set to new Date() by the MikroORM onCreate lifecycle hook; never writable by the API consumer. * updated\_at: set to new Date() on both onCreate and onUpdate by MikroORM lifecycle hooks. * deleted\_at: null on creation; set by the application soft-delete pattern. All active-record queries filter WHERE deleted\_at IS NULL. * Partial index idx\_account\_balances\_current on (account\_pk, balance\_at\_from DESC, pk DESC) WHERE balance\_at\_to IS NULL AND deleted\_at IS NULL โ€” enables an index-only scan with LIMIT 1 for the 'current balance' lookup pattern. * Partial index idx\_account\_balances\_workspace\_deleted on (workspace\_pk, deleted\_at) โ€” optimises the Hasura permission filter (workspace\_pk = \$1 AND deleted\_at IS NULL) on the hot read path. * verification\_error, verification\_error\_detail, calculated\_balance\_diff, expected\_balance\_diff, verified\_at, verification\_last\_run\_at: all populated exclusively by the reconciliation pipeline; never set by the ingestion connector or by edge API writes. * raw\_data: written once by the ingestion connector at sync time; treated as an immutable audit trail. Shape is connector-specific (e.g. Plaid account/balance JSON). * accounting\_balance and foreign\_exchange: written by the connector sync pipeline from provider-native balance data. Not editable via the public API. ## Example ```json theme={null} { "data": { "type": "account_balance", "id": "c3f8d2a1-4e57-4b2c-9a1d-88f702b63c14", "attributes": { "account_balance_id": "c3f8d2a1-4e57-4b2c-9a1d-88f702b63c14", "accounting_balance": { "opening_booked": 142500.00, "opening_value": 142500.00, "closing_booked": 138920.50, "closing_value": 138920.50, "currency": "EUR" }, "foreign_exchange": [ { "currency_rate": 1.0832, "currency_pair": "EUR/USD", "currency_rate_source": "ECB", "currency_rate_at": "2026-05-31T00:00:00.000Z" } ], "balance_at_from": "2026-05-01T00:00:00.000Z", "balance_at_to": "2026-05-31T23:59:59.000Z", "verified_at": "2026-06-01T06:15:22.000Z", "verification_error": false, "verification_error_detail": null, "calculated_balance_diff": 0, "expected_balance_diff": 0, "verification_last_run_at": "2026-06-01T06:15:22.000Z", "raw_data": null, "created_at": "2026-05-01T04:00:12.000Z", "updated_at": "2026-06-01T06:15:22.000Z", "deleted_at": null }, "relationships": { "account": { "data": { "type": "account", "id": "a1b2c3d4-0001-4000-8000-000000000001" } }, "workspace": { "data": { "type": "workspace", "id": "w9f8e7d6-0001-4000-8000-000000000001" } }, "transactions": { "data": [ { "type": "transaction", "id": "t0000001-0001-4000-8000-000000000001" }, { "type": "transaction", "id": "t0000002-0001-4000-8000-000000000002" } ] } } } } ``` Source: `apps/api/src/database/entities/AccountBalance.ts` ยท domain: financial-graph ยท tier: Supporting