Automating Balance Assertions
Balance assertions allow you to verify that Beancount’s computed balance for an account is the same as the balance provided by the banking institution. Auto-generated balance assertions are key to ensuring integrity of your imports. Without auto-generated balance assertions, one of the following occurs, in my experience:
- you end up with incorrect data. When you eventually realize this, the lack of periodic balance assertions means the data range you have to debug is large
- you end up manually adding balance assertions. However:
- this does not scale beyond an account or two with a commodity each. So it does not work for investment accounts, for example.
- what is not automated tends to not get done, meaning you end up with the lack of balance assertions, eventually running into large data ranges to debug when a discrepancy inevitably occurs
Bottomline: automatic balance assertions are critical to updating your ledger in five minutes
OFX files and Balance Assertions
OFX files typically contain balances for each currently held commodity, making this trivial. The investment and banking transaction builders turn these into beancount balance assertions.
CSV files and Balance Assertions
CSV files may or may not contain balances. You have a few options if your institution does not support OFX:
- Some CSV files, especially from banking (not investment) institutions, contain a balance column, showing the balance after each transaction. If yours does, simply extract the balance amount from the last completed transaction (and optionally, the first transaction), and create balance assertions
- If your institution allows it, download a separate CSV file with balances. Schwab makes a CSV available that lists the current balances of each account you own. The Schwab CSV Balance importer imports balances using the multitable reader
- Import the balances pseudo-manually by copy/pasting your balances or positions into a text file from which you can generate balance assertions
- Use fava’s built-in up-to-date indicators (github thread) to copy/paste your balance into your source after verifying it at your institution
You should aim for having not more than one or two exceptions (ideally, zero) to having importers without automated balance assertions for the reasons listed at the beginning of this article.
The Balance Assertion Date
The date of the balance assertion matters. Consider this example of an OFX file for a credit card:
- posting date of first/last transactions: Jan 1 – Jan 31
- statement download date: Feb 3
Is Feb 3 a good choice to to assert balance? Typically not. Subsequent OFX statement downloads might include currently uncleared transactions for say, Feb 2, which would invalidate the Feb 3 assertion, requiring an annoying manual intervention to fix. See this thread.
smart dates: to attempt to avoid this, a good idea is to set the balance assertion
date to either two days before the statement’s end date as claimed by the ofx (the two
days being a fudge factor to account for pending transactions) or to the last
transaction’s date, whichever is later.
beancount_reds_importers
offers several choices. The date of the generated balance assertion can be specified as a key in
the importer config, balance_assertion_date_type, which can be set to:
-
smart: smart date (default). To choose a different fudge factor for smart dates, simply setbalance_assertion_date_fudgein your config. -
ofx_date: date specified in ofx file -
last_transaction: max transaction date -
today: today’s date
If you want something else, simply override this method in individual importer. I use
the smart option, which has been consistent and dependable for me.