Inventory Management in Beancount
Beancount's inventory system is a powerful feature for tracking assets that are bought and sold over time, such as stocks, mutual funds, or foreign currencies. It allows for precise tracking of cost basis, which is essential for calculating capital gains and understanding portfolio performance. This tutorial covers the core mechanics of managing inventories in your ledger.
Core Concepts
At its heart, inventory management revolves around tracking positions. A "position" is simply an amount of a commodity held in an account. Beancount distinguishes between two fundamental types of positions.
Position Types
-
Simple Position (No Cost): This is a standard balance posting. It represents an amount of a commodity without any associated acquisition cost. It's suitable for cash or simple balance assertions.
Assets:Bank:Checking 100.00 USD
-
Position with Cost Basis: This type of position includes not only the number of units and the commodity but also the cost at which it was acquired. This is the foundation of inventory tracking. The cost is specified within curly braces
{}
.Assets:Invest:VTSAX 10 VTSAX {100.00 USD, "lot-1"}
In this example, we hold 10 units of
VTSAX
. Each unit was acquired at a cost of $100.00 USD. This specific batch of shares is identified as a "lot."
Inventory Operations
There are two primary operations you can perform on an inventory:
-
Augmentations (Adding to inventory): When you buy a commodity, you augment your inventory. You create a new lot with a specific number of units and a cost basis.
2024-01-15 * "Buy shares"
Assets:Invest:STOCK 50 STOCK {25.00 USD, "lot-1"}
Assets:Bank:Checking -1250.00 USDHere, we buy 50 units of
STOCK
at a per-unit cost of $25.00 USD. This creates a lot in theAssets:Invest:STOCK
account. -
Reductions (Removing from inventory): When you sell a commodity, you reduce your inventory. You must specify which lot you are selling from. This is done by providing matching information in the curly braces.
2024-01-20 * "Sell shares"
Assets:Invest:STOCK -25 STOCK {25.00 USD}
Assets:Bank:Checking 625.00 USD