8 posts tagged with "finance"

Real estate transactions may constitute the largest financial activity in a family's lifetime. This article explains how to model real estate in Beancount. I treat real estate as an asset and the appreciation of the house as unrealized gain. Additionally, the mortgage is modeled as a liability, and the interest is considered an expense.

Let's assume that Mr. A purchased a luxury home located at 123 ABC Street, XYZ City, CA, 12345 on January 1, 2020, for a price of 1 million. The interest rate is 3.0%, the down payment is 20%, and the loan amount is 800,000.

Create Accounts​

Firstly, we treat the house as an Asset. Since the house is being listed as an Asset, it needs to be given a unit. In this case, the unit quantity is only one, it's unlikely there will be multiple, and even if it's the nth house, we would want to record it in a separate Asset. That is to say, one house corresponds to one Asset, and this Asset has a special unit, its value can only possibly be 1.

2019-12-31 commodity HOUSE.ABC
  name: "123 ABC Street, XYZ City, CA, 12345"

2019-12-31 open Assets:Property:US:CA:123ABC                        HOUSE.ABC
2019-12-31 open Liabilities:Bank:US:SomeBank:Mortgage:Loan          USD

In the first line here, we defined a commodity unit representing the house. In the fourth line, we defined an Asset account, which holds the commodity unit previously defined as the house. In the fifth line, we defined an account for the lending bank. As it's a liability, it falls under the Liabilities category.

Purchase​

With the accounts set up as above, the act of buying a house is equivalent to

borrowing money (debt) + spending money (down payment) = 1 house in asset

The most important reference when buying a property is likely the Buyer’s Settlement Statement, which clearly outlines the flow of money.

2020-01-01 * "Buying the house"
    Assets:Property:US:CA:123ABC                  1 HOUSE.ABC {1,000,000 USD}
    Assets:Bank:US:SomeBankA                      -100,000 USD
    Assets:Bank:US:SomeBankB                      -101,000 USD
    Liabilities:Bank:US:SomeBank:Mortgage:Loan    -800,000.00 USD
    Expenses:Home:Insurance                       1,000 USD
    Expenses:Home:Mortgage:Loan:ClosingCost

Here, we're detailing the transaction of buying the house, where money flows out from some banks (used for down payment and other expenses), a loan is taken (adding to liabilities), and a house is gained (added to assets).

Pay back mortgages​

Based on the above purchase record, we currently owe 800,000 USD. Due to the interest, and considering that all loans in the US are amortized equally in terms of principal and interest, the monthly payment includes a portion for interest and a portion for principal. In the early stages, the interest constitutes the majority.

To record the loan repayment, all you need to do is check your loan bank's statement. You just need to know how much of the principal you are repaying each month, and the rest is interest. The interest is counted as an Expense.

2020-02-01 * "Mortgage payment"
    Assets:Bank:US:SomeBank:Saving:Joint              -3,372.83 USD
    Liabilities:Bank:US:SomeBank:Mortgage:Loan         1,376.26 USD
    Expenses:Home:Mortgage:Loan:Interest

This entry details the monthly mortgage payment which is subtracted from your joint savings account. The repayment of principal reduces the liability, while the interest part is treated as an expense.

Appreciation​

If you want to record the appreciation of the property, some people create a separate account[, only recording the appreciation of the current property. Considering that the value of the house may increase or decrease, this appreciation may be negative. The advantage of this is that in the summary of your total assets, these two accounts will be included, one for the value of the house at the time of the transaction, and the other for the current appreciation of the house, thus reflecting the real-time price of the house.

I did not adopt this method, mainly for the following reasons:

1. The current value of the house can only be an estimate, for reference only, without practical value. Usually, I can only get the evaluation of the property on websites like Redfin or Zillow, and I personally don't think it has high reference value. I also did not consider incorporating these appreciations into total assets in real time.
2. Personally, I think before the mortgage is paid off, if the cash flow of the house is negative, to some extent, the property is still a liability. Therefore, incorporating it into assets prematurely will give you an illusion of enriched assets and appreciation, and I personally want to avoid this illusion.

The method I use to record property appreciation, which will also be discussed later on how to model RSUs. This method is to use a virtual currency unit. Assuming your base currency is USD, we can use USD.UNVEST (it seems that there is no need to create a new Commodity for this) to indicate that this asset is calculated in a special currency. The growth or reduction of this asset will not be recorded in USD. This way, I can achieve my original goal, that is, to record the appreciation of the house, and this appreciation will not be included in the final balance sheet (Balance Sheet).

2020-01-01 price HOUSE.ABC                          1,000,000 USD
2025-01-01 price HOUSE.ABC                          1,400,000 USD.UNVEST

You only need to price your property to USD.UNVEST regularly.

So, on Fava's Commodity page, you can track the trend of the reference price of the house. But on the Balance Sheet page, the price of the house is still the price of the house at the time of the transaction. That is to say, your total assets are still your down payment money at that time, plus the principal you keep paying off. The final change of this asset should only occur when you buy a house.

Sell​

Because no property has been sold yet and the various miscellaneous fees in the middle are unclear, this is a hypothetical scenario.

Suppose, on January 1, 2025, the property has appreciated to $1,400,000, and some reference data are as follows:

Person A decides to sell the property, and the final selling price of the house is $1,300,000.

2025-01-01 * "Selling the house"
    Assets:Property:US:CA:123ABC                  -1 HOUSE.ABC {1,300,000 USD}
    Liabilities:Bank:US:SomeBank:Mortgage:Loan    709,656.20 USD
    Expenses:Home:Agent:Fee                       72,000 USD
    Expenses:Home:ClosingCost                     10,000 USD
    Expenses:Home:Tax                             90,000 USD
    Assets:Bank:US:SomeBankA

Here it is assumed that 2 out of 5 years are self-occupied, so the appreciation of 500,000 does not need to be taxed. I randomly calculated a number here. In the end, the money that enters Person A's account is $418,343.8, of which 200,000 is the down payment at that time, and about 100,000 in interest has been paid. So, in the end, the book profit for Person A is around 100,000. It is worth noting that my calculation is not fair, after all, Person A has saved rent for these 5 years, and there may be other expenses on the house, such as maintenance, decoration, and so on.

To reflect this in the balance sheet, you can add this pricing.

2025-01-01 price HOUSE.ABC                          1,300,000 USD

Hello everyone! In today's blog post, we're diving into the world of Beancount, a double-entry accounting tool that's loved by many for its simplicity and power. More specifically, we're going to talk about two key concepts: Receivables and Payables.

Understanding these terms is crucial to using Beancount (or any double-entry accounting system) effectively. But don't worry if you're a beginner - we're going to break it all down, step by step!

Receivables and Payables: The Basics​

In accounting, "receivables" and "payables" are terms used to track money that is owed. "Receivables" refers to money that others owe to you, while "payables" refers to money that you owe to others.

Let's take an example:

1. Accounts Receivable (A/R): Suppose you own a bookstore and a customer buys a book on credit. The money they owe you for the book is an account receivable.

2. Accounts Payable (A/P): On the flip side, imagine you order a new set of books from a publisher, but you don't pay for them upfront. The money you owe the publisher is an account payable.

In Beancount, these are typically tracked through corresponding accounts. The main benefit here is that it provides you with a clear and accurate picture of your financial position at any point in time.

Setting Up Receivables and Payables in Beancount​

The structure of your Beancount file can be as simple or as complex as you need it to be. For receivables and payables, you'll likely want to create separate accounts under your Assets and Liabilities sections.

Here is a simple example:

1970-01-01 open Assets:AccountsReceivable
1970-01-01 open Liabilities:AccountsPayable

Tracking Transactions​

Payee side​

After setting up your accounts, you can track transactions that involve receivables and payables. Let's look at an example:

2023-05-29 * "Sold books to customer on credit"
  Assets:AccountsReceivable  100 USD
  Income:BookSales          -100 USD

Here, you're adding $100 to your receivables because a customer owes you this amount. Simultaneously, you're reducing your income by the same amount to maintain the balance (since you haven't actually received the money yet).

When the customer eventually pays, you'll record it like this:

2023-06-01 * "Received payment from customer"
  Assets:Bank:Savings        100 USD
  Assets:AccountsReceivable -100 USD

Payer side​

The same principle applies for payables, but with reversed signs:

2023-05-30 * "Bought books from publisher on credit"
  Liabilities:AccountsPayable  200 USD
  Expenses:BookPurchases     -200 USD

And when you pay off your debt:

2023-06-02 * "Paid off debt to publisher"
  Liabilities:AccountsPayable -200 USD
  Assets:Bank:Checking        200 USD

Wrapping Up​

Receivables and payables are at the heart of any accounting system. By accurately tracking these, you gain a comprehensive understanding of your financial health.

This is just a starting point, and Beancount is capable of much more. I hope this blog post helps clarify these important concepts. As always, happy accounting!

Example Account Name​

Assets:US:BofA:Checking

Account Types​

Assets          +
Liabilities     -
Income          -
Expenses        +
Equity          -

Commodities​

CNY, EUR, CAD, AUD
GOOG, AAPL, RBF1005
HOME_MAYST, AIRMILES
HOURS

Directives​

General syntax

YYYY-MM-DD <Directive> <Parameters...>

Opening & Closing Accounts​

2001-05-29 open Expenses:Restaurant
2001-05-29 open Assets:Checking     USD,EUR  ; Currency constraints

2015-04-23 close Assets:Checking

Declaring Commodities (Optional)​

1998-07-22 commodity AAPL
  name: "Apple Computer Inc."

Prices​

2015-04-30 price AAPL   125.15 CNY
2015-05-30 price AAPL   130.28 CNY

Notes​

2013-03-20 note Assets:Checking "Called to ask about rebate"

Documents​

2013-03-20 document Assets:Checking "path/to/statement.pdf"

Transactions​

2015-05-30 * "Some narration about this transaction"
  Liabilities:CreditCard   -101.23 CNY
  Expenses:Restaurant       101.23 CNY

2015-05-30 ! "Cable Co" "Phone Bill" #tag ˆlink
  id: "TW378743437"               ; Meta-data
  Expenses:Home:Phone  87.45 CNY
  Assets:Checking                 ; You may leave one amount out

Postings​

  ...    123.45 USD                             Simple
  ...        10 GOOG {502.12 USD}               With per-unit cost
  ...        10 GOOG {{5021.20 USD}}            With total cost
  ...        10 GOOG {502.12 # 9.95 USD}        With both costs
  ...   1000.00 USD   @ 1.10 CAD                With per-unit price
  ...        10 GOOG {502.12 USD} @ 1.10 CAD    With cost & price
  ...        10 GOOG {502.12 USD, 2014-05-12}   With date
  ! ...   123.45 USD ...                        With flag

Balance Assertions and Padding​

; Asserts the amount for only the given currency:
2015-06-01 balance Liabilities:CreditCard  -634.30 CNY

; Automatic insertion of transaction to fulfill the following assertion:
2015-06-01pad Assets:Checking Equity:Opening-Balances

Events​

2015-06-01 event "location" "New York, USA"
2015-06-30 event "address" "123 May Street"

Options​

option "title" "My Personal Ledger"

Other​

pushtag #trip-to-peru
...
poptag  #trip-to-peru
; Comments begin with a semi-colon

Discover the Magic of Plain Text Accounting with Beancount

Introduction​

Welcome to a world where accounting is no longer a daunting task. Today, we introduce you to Beancount, a powerful, flexible, and intuitive plain text accounting tool. Beancount empowers you to take control of your finances by providing a transparent and straightforward approach to managing your money.

In this comprehensive guide, we will delve into the basics of Beancount, explain its core concepts, and walk you through its simple yet powerful features. By the end of this blog, you'll have a solid understanding of Beancount and be ready to start using it to organize and analyze your financial life.

What is Beancount?​

Beancount is an open-source, plain text accounting system created by Martin Blais. Inspired by John Wiegley's Ledger system, Beancount aims to provide a robust and reliable method to manage personal and small business finances using plain text files. With Beancount, you can track your income, expenses, investments, and much more with ease.

Why Beancount?​

Plain text accounting offers several advantages over traditional spreadsheet-based or software-based accounting systems:

• Transparency: Beancount files are human-readable, making it easy to understand and audit your financial data.
• Flexibility: Beancount can be easily customized to fit your specific needs, and you can use your favorite text editor and version control system to manage your financial data.
• Portability: Your financial data can be accessed on any device, and it's easy to transfer between systems or share with others.
• Future-proof: Plain text files are universally compatible, ensuring that your financial data will remain accessible, even as technology evolves.

Beancount's Core Concepts​

To use Beancount effectively, it's crucial to understand its core concepts:

• Transactions: Financial events, such as income, expenses, or transfers between accounts, are recorded as transactions.
• Accounts: Transactions involve one or more accounts, such as assets, liabilities, income, or expenses.
• Double-entry bookkeeping: Beancount enforces double-entry bookkeeping, ensuring that every transaction has balanced debits and credits.
• Directives: Beancount uses a set of directives to define transactions, account openings, and other financial events.

Getting Started with Beancount​

To start using Beancount, follow these simple steps:

• Install Beancount: Install Beancount on your system using the provided installation instructions for your operating system.
• Create your Beancount file: Create a new plain text file with the .beancount extension (e.g., my_finances.beancount).
• Define your accounts: Use the "open" directive to define the accounts you'll use in your transactions.
• Record transactions: Use the "txn" directive to record your financial transactions.

Or simply sign up at https://beancount.io. Here are some plain text accounting examples -

Example 1: Basic Transaction

2023-04-01 open Assets:Checking
2023-04-01 open Expenses:Groceries

2023-04-10 txn "Grocery Store" "Buying groceries"
  Assets:Checking         -50.00 USD
  Expenses:Groceries       50.00 USD

In this example, we open two accounts, Assets:Checking and Expenses:Groceries. On April 10, 2023, we record a transaction for buying groceries worth $50. The transaction reduces the balance of Assets:Checking by $50 (debit) and increases the balance of Expenses:Groceries by $50 (credit).

Example 2: Income and Expense Transaction

2023-04-01 open Assets:Checking
2023-04-01 open Income:Salary
2023-04-01 open Expenses:Rent

2023-04-05 txn "Employer" "Salary payment"
  Assets:Checking       2000.00 USD
  Income:Salary        -2000.00 USD

2023-04-06 txn "Landlord" "Monthly rent payment"
  Assets:Checking       -1000.00 USD
  Expenses:Rent          1000.00 USD

In this example, we open three accounts: Assets:Checking, Income:Salary, and Expenses:Rent. On April 5, 2023, we record a salary payment transaction of $2000. The transaction increases the balance of Assets:Checking by $2000 (credit) and decreases the balance of Income:Salary by $2000 (debit). On April 6, 2023, we record a rent payment transaction of $1000. The transaction reduces the balance of Assets:Checking by $1000 (debit) and increases the balance of Expenses:Rent by $1000 (credit).

Example 3: Transfer Between Accounts

2023-04-01 open Assets:Checking
2023-04-01 open Assets:Savings

2023-04-15 txn "Bank" "Transfer from Checking to Savings"
  Assets:Checking       -500.00 USD
  Assets:Savings         500.00 USD

In this example, we open two accounts: Assets:Checking and Assets:Savings. On April 15, 2023, we record a transaction to transfer $500 from the checking account to the savings account. The transaction reduces the balance of Assets:Checking by $500 (debit) and increases the balance of Assets:Savings by $500 (credit).

These examples illustrate the basic concepts of Beancount's double-entry bookkeeping system. By properly recording transactions, users can maintain accurate records of their financial activities and generate reports to gain insights into their financial situation.

Generating Reports and Analyzing Data​

Beancount comes with a set of powerful tools for generating financial reports, including balance sheets, income statements, and more. You can also use Fava, a web-based user interface for Beancount, to visualize and interact with your financial data. https://beancount.io is built upon Fava with MIT license.

Conclusion​

Embrace the power and simplicity of plain text accounting with Beancount. By understanding its core concepts and following the steps outlined in this guide, you'll be well on your way to managing your personal or small business finances with ease and precision. As you grow more comfortable with Beancount, you can explore advanced features and customizations to tailor the system to your unique needs.

Whether you're looking to track your spending, plan for the future, or gain insights into your financial habits, Beancount offers the flexibility and transparency needed to achieve your goals. With its user-friendly approach, Beancount has the potential to revolutionize the way you manage your finances and empower you to take control of your financial future.

Now that you have a solid foundation in Beancount, it's time to embark on your plain text accounting journey. Say goodbye to cumbersome spreadsheets and convoluted software, and welcome the world of Beancount. Happy accounting!

Beancount, the double-entry accounting system beloved by developers and finance nerds alike, is powerful in its simplicity. But for those who want more control and faster navigation inside Fava, Beancount’s web interface, custom sidebar links and SQL queries can take your workflow to the next level.

In this guide, we’ll show you how to:

• Add quick-access links to Fava’s sidebar
• Use SQL queries for advanced filtering and analysis
• Customize your workflow for monthly reviews or anomaly detection

Why Customize Fava?​

Fava is already a beautiful interface for viewing your Beancount ledger, but as your journal grows, so does the need for better shortcuts and smarter queries.

Pain points this solves:​

• Navigating through time ranges repeatedly
• Filtering transactions across nested accounts
• Spotting negative balances or anomalies faster

✨ Custom Sidebar Links​

Let’s start with improving your daily workflow with simple sidebar shortcuts. These links appear in Fava’s left sidebar and can take you directly to filtered views like this month’s transactions or last month’s income.

Add these lines to your Beancount file:

2021-01-01 custom "fava-sidebar-link" "Current Month" "/jump?time=month"
2021-01-01 custom "fava-sidebar-link" "Last Month" "/jump?time=month-1"
2021-01-01 custom "fava-sidebar-link" "Clear All" "/jump?account=&time=&filter="

What They Do:​

• Current Month: Opens the transaction view filtered to the current month.
• Last Month: Instantly jumps to the previous month—great for end-of-month reviews.
• Clear All: Resets filters, showing all entries again.

These shortcuts eliminate manual time input and make your Fava experience feel more fluid and personalized.

🔍 Custom SQL Queries​

For deeper insight, Fava’s SQL interface is incredibly powerful. Here’s a query that finds all negative balances in accounts that match a pattern—perfect for flagging unusual or problematic transactions.

SELECT account, units(sum(position)), sum(position)
WHERE number(units(position)) < 0
  AND account ~ '.*:BCM:.*'
  AND date >= DATE(2021,12,9)
  AND date < DATE(2022,1,9)

Breakdown:​

• account ~ '.*:BCM:.*': Filters accounts containing :BCM: in their name.
• number(units(position)) < 0: Flags negative balances (e.g. overspent budgets).
• Date filters narrow the result to a specific 1-month window.

Use cases:​

• Spot errors like duplicate expenses or incorrect postings
• Audit a specific vendor or category
• Quickly extract actionable insights for budgeting

🛠 Pro Tip: Combine Links + Queries​

While Fava doesn’t allow direct links to custom queries, you can create a monthly review habit by:

• Using the “Current Month” link to start your review
• Opening your saved queries tab in another pane
• Reviewing both simultaneously—filter first, then dig deep

This combo helps you catch anomalies before they spiral and ensure your ledger stays clean.

Final Thoughts​

Beancount is minimal by design, but small enhancements like these bring huge gains in efficiency. Whether you’re reviewing your budget, debugging strange balances, or simply saving clicks, custom links and SQL queries give you more power and less friction.

Bonus: If you're using Fava’s custom reports, you can even build full dashboards tailored to your personal finance rituals.

Ready to take control?

Start small: add the “Current Month” link. Then build your own queries. Your future self will thank you.

Want more tips like this? Subscribe to our newsletter or explore more Beancount recipes at Beancount.io.

There is a plugin for beancount to forecast future recurring transactions. How to apply it in beancount.io? Put the following content into your ledger file.

; import the plugin
plugin "fava.plugins.forecast"

; add a monthly HOA fee
2022-05-30 # "HOA fee [MONTHLY]"
  Expenses:Hoa                                      1024.00 USD
  Assets:Checking                                  -1024.00 USD

And then, you will see the forecast in Net Profit chart.

The tag [MONTHLY] above means it will recur forever. If you have more conditions to apply, try [MONTHLY UNTIL 2022-06-01], [MONTHLY REPEAT 5 TIMES], [YEARLY REPEAT 5 TIMES], or [WEEKLY SKIP 1 TIME REPEAT 5 TIMES].

Amortization spreads out payments to many installments over time. In beancount.io, you can use the plugin fava.plugins.amortize_over to achieve so.

Without amortization, if you want to insure your car for 6 months with costs of $600. You have to record this as a one-time expense for a particular date.

2017-06-01 open Assets:Bank:Checking
2017-06-01 open Assets:Prepaid-Expenses
2017-06-01 open Expenses:Insurance:Auto

![2021-01-09-amortize](https://opengraph-image.blockeden.xyz/api/og-beancount-io?title=Understanding%20Amortization%20in%20Beancount)

2017-06-01 * "Pay car insurance"
    Assets:Bank:Checking       -600.00 USD
    Assets:Prepaid-Expenses

However, with amortization, you could allocate the expense over six months by putting plugin "fava.plugins.amortize_over" to the top of the file and using amortize_months: 6 for the transaction

plugin "fava.plugins.amortize_over"

2020-06-01 open Assets:Bank:Checking
2020-06-01 open Assets:Prepaid-Expenses
2020-06-01 open Expenses:Insurance:Auto

2020-06-01 * "Amortize car insurance over six months"
    amortize_months: 6
    Assets:Prepaid-Expenses       -600.00 USD
    Expenses:Insurance:Auto

And then in Journal, you will see the transaction is split into 6 postings.

2020-11-01 * Amortize car insurance over six months (6/6) am
2020-10-01 * Amortize car insurance over six months (5/6) am
2020-09-01 * Amortize car insurance over six months (4/6) am
2020-08-01 * Amortize car insurance over six months (3/6) am
2020-07-01 * Amortize car insurance over six months (2/6) am
2020-06-01 * Amortize car insurance over six months (1/6) am

Beancount users often give us feedback that it is painful to add an entry to the ledger on mobile devices. Today, we are glad to announce the first-ever Beancount iOS App and Android App.

This App makes it easy to add transactions to your ledger and view some financial reports on your phone. And you can also edit the ledger file directly via the web view. Your usage of this App will determine what features we will add in the future. Please feel free to join our community and discuss Beancount and bookkeeping at https://t.me/beancount.

Our mission is to help people live a better financial life, and Beancount App is just a very initial step of what we are planning to achieve. There is an Android one pending in review. And more tools are coming soon.