One of the first steps to mastering Beancount is designing a clean, flexible, and future-proof Chart of Accounts (CoA). This structure defines how you categorize your financial life—and ultimately, how useful and insightful your reports will be.

In this post, I’ll walk through the principles, pitfalls, and patterns I’ve learned while building my own CoA in Beancount.

Principles

I have been using Beancount for a few years. Over these years, I changed the CoA many times. I found that the following three high level principles can be a good starting point for designing your accounts structure:

• The hierarchy should reflect the most common aggregations you want to see in your ledger.
• Is it simple enough that you do not need to folding too deep the hierarchy.
• Consistent with the real financial life, which makes it easy to a balance check.

It is hard to design a good generic convention. Firstly, I find that the hierarchy structure depends on account type. The CoA of Asset accounts should have different naming convention from the Expenses accounts. Secondly, it also highly depends on your personal life and requirements. When I started to use Beancount to manage my finance, I was a poor doctoral student at the time. The CoA was quite simple for me. Then, over the years, I get married, form a family and have a beautiful daughter. Due to these life changes, I have to change the account structure to adjust these changes. So, I do not think that designing a fit CoA is a once-for-all job, instead, it is an evolving process.

Due to these complexities, I do not think I can provide a universal naming convention. So, I plan to list a few questions for each account type that I am most interested in and based on these questions, I give a few examples of the accounts I have. Readers can develop their own questions then design their own CoA.

CoA Examples

Asset Accounts

I think the Asset account type is the one that requires most frequent changes comparing to other account types.

For the Asset account type, I am mostly interested in the following questions:

• How much is cash I have to can support my daily life? (cover all the current liabilities, grocery, utility fees, etc.)
• How much do I have for the emergency fund?
• How much investment I own?
• What is left in my Health accounts (HSA and FSA)
• How much do I have for the retirement accounts

Slightly different from Martin’s name convention, I am using the following naming convention for the Asset account type¹:

1

Type:Purpose:Asset Class:Institution:Account:SubAccounts

The purpose represents how do you categorize the assets you have. For me, I categorize all my assets into:

• Cash: The cash in general senses, usually including all the checking accounts. This kind of asset is used to cover all my family’s daily life expense.
• Emergency fund: as the name suggest, it is the asset set-aside for emergency events. It can be in the form of saving accounts or CD or any other asset class you feel safe about.
• Investment: this is the asset I want to make more asset, mostly in the form of stocks, bonds or real estates.
• Health accounts: this is the health accounts including FSA and HSA accounts.
• Retirement accounts: In US, we have some special investment accounts for our retirement. Usually we cannot withdraw from these accounts until you reach the age requirements. So, basically these are the assets you have, but you cannot use right now. So, I separate them from other assets.

The good thing of this convention is I can quickly find the answers for the above questions with the help of Fava.

Some account naming examples:

1
2
3

Assets:Cash:Checking:Chase
Assets:Emergency:Saving:Discover
Assets:Investment:Stock:Fidelity:Playground:VOO

Incomes

Incomes type is the second most frequent accounts you will change because you probably will change your job or start your own business over the years. Once these changes happen, you will have to adjust your Incomes accounts accordingly.

For me, I am mostly interested in the following questions:

1. What is the total/monthly gross income from this Employer?
2. What is the total/monthly benefits that this Employer provides?
3. What is my total/monthly investment income?

To make the data importing easy, we probably need to be consistent with the pay checks items if you are a W2 worker.

To answer these questions, some examples are:

1
2
3

Income:Investments:Stock:Fidelity:Yichu:Playground:VOO:Dividend
Income:Work:Employer:Earnings:Regular
Income:Work:Employer:Benefits:401KMatch

Expenses

I do not think Expenses accounts (as well as Liabilities) require frequent changes over the time. Maybe adding a few branches on the hierarchy, but usually do not require major changes.

There are many other financial accounting apps that predefined a bunch of expenses accounts. We can easily follow them.

For the expenses, I have the following questions:

1. How much I am paying for the taxes?
2. How much is the daily expenses?

So, as a result, my Expenses account naming is quite simple²:

1
2
3
4
5

Expenses:NonTaxes:Daily:Grocery
Expenses:NonTaxes:Daily:Restaurants
Expenses:Taxes:FederalIncomeTax:Withhold
Expenses:Taxes:FederalIncomeTax:Payment
Expenses:Taxes:FederalIncomeTax:Refund

Liabilities

I think the Liabilities accounts are most fixed accounts. It probably does not need change. And the questions are also quite simple:

• What are the current/credit card Liabilities?
• What are the outstanding mortgage?

Examples:

1
2

Liabilities:Current:CreditCard:Chase
Liabilities:Non-current:Mortgage:Location123:Chase

Virtual Accounts

One more thing I want to add here is the use of virtual accounts. In most cases, because we want to be consistent with the actual financial accounts, we do not need virtual accounts. But I do find some use cases that suitable for the virtual accounts:

• My wife and I have a joint checking account. We will deposit a portion of our salary into this joint account to cover our daily expenses. You might want to keep tracking how much you (or your partner) have deposited into this account. For this use case, we can have two virtual accounts under this joint account:

1
2

Assets:Cash:Checking:WellsFargo:Joint:Partner1
Assets:Cash:Checking:WellsFargo:Joint:Partner2

When one of the partners make a deposit:

1
2
3
4

2025-01-31 "Employer"
    Income:Work:Employer:Earnings:Regular -3,000 USD
    Assets:Cash:Checking:WellsFargo:Joint:Partner1 2,000 USD
    ...

In this way, we can keep tracking the individual contributions as well as the total amount of this joint account.

Suggestions

• Start with simple and intuitively make sense to you.
• Be prepared to make changes. Financial life changes over time. Buying a house or running a side business can impact your view of you ledger.
• No need to include everything into a CoA. More information can be added using metadata. For example, the tax related information.

1
2
3

    2025-01-01 open Assets:Bank:Checking USD
        bank: "First National Bank"
        account_number: "123456789"

This information can be useful for identification and integration with other financial tools.