# Beancount lots, cost basis and booking methods

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](https://beancount.io/docs/tax-prep-guides) 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

1. **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](https://beancount.io/docs/Basics/syntax).

   ```bean
   Assets:Bank:Checking      100.00 USD
   ```

2. **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 `{}`.

   ```bean
   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:

1. **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.

   ```bean
   2024-01-15 * "Buy shares"
     Assets:Invest:STOCK     50 STOCK {25.00 USD, "lot-1"}
     Assets:Bank:Checking   -1250.00 USD
   ```

   Here, we buy 50 units of `STOCK` at a per-unit cost of $25.00 USD. This creates a lot in the `Assets:Invest:STOCK` account.

2. **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.

   ```bean
   2024-01-20 * "Sell shares"
     Assets:Invest:STOCK    -25 STOCK {25.00 USD}
     Assets:Bank:Checking    625.00 USD
   ```

   In this transaction, we are selling 25 units of `STOCK` from the lot that was purchased at $25.00 USD per unit.

## Booking Methods

When you reduce an inventory, Beancount needs a rule to decide which specific lot to pull from if several lots match the reduction. This rule is called the "booking method." You can set a default for the whole file with an option, or give one account its own method on the `open` directive.

Beancount 3.2.3 accepts seven method names: `STRICT` (the default), `STRICT_WITH_SIZE`, `NONE`, `FIFO`, `LIFO`, `HIFO` and `AVERAGE`. Six of them are implemented; `AVERAGE` parses but raises an error the moment it has to book a reduction, as the **AVERAGE** section below shows.

### 1\. STRICT (Default)

The `STRICT` method is the default and the safest booking method. It enforces explicit and unambiguous matching.

```bean
2024-01-01 open Assets:Invest:STOCK "STRICT"
```

- **Requires Exact Lot Match**: The reduction posting's cost specifier (`{...}`) must identify a single lot — by cost, by acquisition date, by label, or by any combination of them.
- **Errors on Ambiguous Matches**: If the specifier matches more than one lot, Beancount raises an `AmbiguousMatchError` instead of guessing.
- **Exception**: If a reduction removes exactly the total number of units the specifier matches, an empty specifier (`{}`) is allowed, and the reduction is split across those lots.

This ledger holds two lots and sells one of them by naming its cost, which is unambiguous:

```bean
1970-01-01 commodity STK
1970-01-01 open Assets:Broker:Strict  STK  "STRICT"
1970-01-01 open Assets:Broker:Cash    USD
1970-01-01 open Income:Gains          USD

2024-01-10 * "Buy the first lot"
  Assets:Broker:Strict    10 STK {100.00 USD}
  Assets:Broker:Cash   -1000.00 USD

2024-02-10 * "Buy the second lot"
  Assets:Broker:Strict    10 STK {120.00 USD}
  Assets:Broker:Cash   -1200.00 USD

; The cost identifies exactly one lot, so STRICT is satisfied.
2024-06-01 * "Sell the $120.00 lot"
  Assets:Broker:Strict   -10 STK {120.00 USD} @ 150.00 USD
  Assets:Broker:Cash    1500.00 USD
  Income:Gains
```

It loads without errors, books $300.00 of gain to `Income:Gains`, and leaves `10 STK {100.00 USD}` in the account.

Replace that last posting with an empty specifier and the same file **fails**:

```bean
; Rejected under STRICT: "-10 STK {}" matches both lots.
2024-06-01 * "Sell 10 shares"
  Assets:Broker:Strict  -10 STK {} @ 150.00 USD
  Assets:Broker:Cash   1500.00 USD
  Income:Gains
```

Beancount reports `Ambiguous matches for "-10 STK {}"` and lists the candidates. Selling the *whole* position is fine, though, because there is nothing left to choose between:

```bean
; Allowed under STRICT: -20 STK is the entire holding, so the empty
; specifier is split across both lots.
2024-06-01 * "Close the position"
  Assets:Broker:Strict  -20 STK {} @ 150.00 USD
  Assets:Broker:Cash   3000.00 USD
  Income:Gains
```

That books $800.00 of gain — $3,000.00 of proceeds against $1,000.00 + $1,200.00 of basis — and leaves the account empty. This is a property of `STRICT` itself, not something you have to switch to `STRICT_WITH_SIZE` for.

### 2\. FIFO (First-In, First-Out)

The `FIFO` method automatically books reductions against the oldest available lots first.

```bean
2024-01-01 open Assets:Invest:STOCK "FIFO"
```

- **Automatic Resolution**: It resolves ambiguity by selecting the oldest matching lots.
- **Chronological Matching**: You assume you are selling the assets you have held the longest. Several tax authorities treat this as the default when you have not identified a lot.

### 3\. LIFO (Last-In, First-Out)

The `LIFO` method is the opposite of FIFO. It books reductions against the **newest** available lots first.

```bean
2024-01-01 open Assets:Invest:STOCK "LIFO"
```

- **Reverse Chronological Order**: It selects the most recently acquired matching lots.
- **Newest, not most expensive**: LIFO picks by acquisition date only. It happens to sell the highest-cost shares when prices have been rising, but if your newest lot is your cheapest — which is what the example below is built to show — LIFO will realize the *largest* gain, not the smallest. The method that always sells the most expensive shares is `HIFO`, described next.

### 4\. HIFO (Highest-In, First-Out)

The `HIFO` method books reductions against the **most expensive** available lots first, whatever their date.

```bean
2024-01-01 open Assets:Invest:STOCK "HIFO"
```

- **Cost-Ranked Matching**: It selects the matching lots with the highest cost basis.
- **Smallest Realized Gain**: For a given sale price, selling the highest-cost shares realizes the smallest gain (or the largest loss). Whether you may use it is a jurisdiction question — in the United States, for example, choosing a lot at all requires specific identification at the time of sale — so treat the method as a bookkeeping mechanism and confirm the tax election separately.

### 5\. Comparing FIFO, LIFO and HIFO on the same lots

The three methods only differ when the oldest, the newest and the most expensive lot are three different lots. This ledger arranges exactly that — lot A is the oldest, lot C is the newest, and the middle lot B is the most expensive — and then sells 10 shares out of three accounts that differ only in their booking method:

```bean
1970-01-01 commodity STK
1970-01-01 open Assets:Broker:Fifo  STK  "FIFO"
1970-01-01 open Assets:Broker:Lifo  STK  "LIFO"
1970-01-01 open Assets:Broker:Hifo  STK  "HIFO"
1970-01-01 open Assets:Broker:Cash  USD
1970-01-01 open Income:Gains        USD

; Lot A - the oldest, at $100.00 per share
2024-01-10 * "Buy lot A"
  Assets:Broker:Fifo     10 STK {100.00 USD}
  Assets:Broker:Lifo     10 STK {100.00 USD}
  Assets:Broker:Hifo     10 STK {100.00 USD}
  Assets:Broker:Cash  -3000.00 USD

; Lot B - the most expensive, at $120.00 per share
2024-02-10 * "Buy lot B"
  Assets:Broker:Fifo     10 STK {120.00 USD}
  Assets:Broker:Lifo     10 STK {120.00 USD}
  Assets:Broker:Hifo     10 STK {120.00 USD}
  Assets:Broker:Cash  -3600.00 USD

; Lot C - the newest, at $90.00 per share
2024-03-10 * "Buy lot C"
  Assets:Broker:Fifo     10 STK {90.00 USD}
  Assets:Broker:Lifo     10 STK {90.00 USD}
  Assets:Broker:Hifo     10 STK {90.00 USD}
  Assets:Broker:Cash  -2700.00 USD

; Sell 10 shares out of each account at $150.00 and let each
; account's booking method choose which lot leaves.
2024-06-01 * "Sell 10 shares from each account"
  Assets:Broker:Fifo    -10 STK {} @ 150.00 USD
  Assets:Broker:Lifo    -10 STK {} @ 150.00 USD
  Assets:Broker:Hifo    -10 STK {} @ 150.00 USD
  Assets:Broker:Cash   4500.00 USD
  Income:Gains
```

It loads with zero errors and books $1,400.00 of gain in total, split like this:

| Account | Method | Lot booked | Cost basis | Realized gain | Lots remaining |
| :------------------- | :----- | :--------------- | ---------: | ------------: | :------------------------------ |
| `Assets:Broker:Fifo` | FIFO   | lot A, 2024-01-10 | $100.00 | $500.00 | 10 @ $120.00, 10 @ $90.00 |
| `Assets:Broker:Lifo` | LIFO   | lot C, 2024-03-10 | $90.00 | $600.00 | 10 @ $100.00, 10 @ $120.00 |
| `Assets:Broker:Hifo` | HIFO   | lot B, 2024-02-10 | $120.00 | $300.00 | 10 @ $100.00, 10 @ $90.00 |

The LIFO row is the one worth staring at: it realized the *biggest* gain of the three, because the newest lot was also the cheapest.

### 6\. STRICT_WITH_SIZE

`STRICT_WITH_SIZE` is `STRICT` plus one extra tie-breaker: when several lots match but exactly one of them holds precisely the number of units you are removing, that lot is chosen.

```bean
1970-01-01 commodity STK
1970-01-01 open Assets:Broker:Sized  STK  "STRICT_WITH_SIZE"
1970-01-01 open Assets:Broker:Cash   USD
1970-01-01 open Income:Gains         USD

2024-01-10 * "Buy 10 shares"
  Assets:Broker:Sized    10 STK {100.00 USD}
  Assets:Broker:Cash  -1000.00 USD

2024-02-10 * "Buy 7 shares"
  Assets:Broker:Sized     7 STK {120.00 USD}
  Assets:Broker:Cash   -840.00 USD

; Only one lot holds exactly 7 units, so the empty specifier resolves.
2024-06-01 * "Sell 7 shares"
  Assets:Broker:Sized    -7 STK {} @ 150.00 USD
  Assets:Broker:Cash   1050.00 USD
  Income:Gains
```

That books $210.00 of gain against the $120.00 lot. The identical file with `"STRICT"` on the `open` line fails with `Ambiguous matches for "-7 STK {}"`.

### 7\. AVERAGE (accepted, but not implemented)

`AVERAGE` is a valid name — `option "booking_method" "AVERAGE"` and `open … "AVERAGE"` both parse — but Beancount 3.2.3 has no implementation behind it. Everything here loads until the sale:

```bean
1970-01-01 commodity STK
1970-01-01 open Assets:Broker:Avg   STK  "AVERAGE"
1970-01-01 open Assets:Broker:Cash  USD
1970-01-01 open Income:Gains        USD

2024-01-10 * "Buy 10 shares at $10.00"
  Assets:Broker:Avg      10 STK {10.00 USD}
  Assets:Broker:Cash  -100.00 USD

2024-02-10 * "Buy 10 more at $8.00"
  Assets:Broker:Avg      10 STK {8.00 USD}
  Assets:Broker:Cash   -80.00 USD

; An average-cost engine would book this at $9.00 per share. This one refuses.
2024-06-01 * "Sell 5 shares"
  Assets:Broker:Avg      -5 STK {}
  Assets:Broker:Cash    45.00 USD
  Income:Gains
```

The moment that reduction has to be booked, the loader stops with:

```text
AVERAGE method is not supported
```

Do not plan a ledger around it. If you want average-cost behaviour today, keep the position in a `NONE` account and compute the average yourself, or track each lot and accept lot-level gains.

### 8\. NONE

The `NONE` method disables lot matching entirely.

```bean
2024-01-01 open Assets:Invest:STOCK "NONE"
```

- **No Lot Matching**: Beancount does not attempt to match reductions to augmentations.
- **Allows Mixed Signs**: This allows an account to hold both positive and negative balances of the same commodity simultaneously. This behavior is similar to how the Ledger CLI tool handles commodities.

## Lot Specification

A "lot" is a specific block of a commodity acquired at a particular time and price. When you create or reduce a position, you can specify its lot attributes in detail.

### Full Specification

When augmenting an inventory (buying), you can specify up to three attributes for the lot, comma-separated inside a single pair of braces:

```bean
Assets:Invest:STOCK  10 STOCK {100.00 USD, 2024-01-15, "lot-identifier"}
```

- `100.00 USD` — the cost basis, expressed **per unit**.
- `2024-01-15` — the acquisition date. Beancount fills this in from the transaction date when you omit it, which is why the error messages above show a date on every lot.
- `"lot-identifier"` — an optional string label.

While all three are optional, providing at least the cost basis is standard practice. The braces must stay on one line, and comments inside a ledger start with `;`, never `#`.

### Matching Methods

When reducing an inventory (selling), you use the same syntax to specify which lot(s) to sell from.

- **Match by cost**: This is the most common method.

  ```bean
  Assets:Invest:STOCK  -5 STOCK {100.00 USD}
  ```

- **Match by date**: If costs are identical, you can disambiguate using the acquisition date.

  ```bean
  Assets:Invest:STOCK  -5 STOCK {2024-01-15}
  ```

- **Match by label**: Labels provide a foolproof way to identify a lot.

  ```bean
  Assets:Invest:STOCK  -5 STOCK {"lot-identifier"}
  ```

- **Leave the lot to the booking method**: An empty set of braces `{}` names no lot, so the account's booking method chooses. Under `FIFO`, `LIFO` or `HIFO` that is the oldest, newest or most expensive matching lot; under the default `STRICT` it is an `AmbiguousMatchError` unless the reduction empties the matched lots exactly.

  ```bean
  Assets:Invest:STOCK  -5 STOCK {}
  ```

## Price Handling

It is crucial to understand the difference between **cost basis** (`{}`) and **price** (`@`). They serve different purposes and are not interchangeable.

### Price vs Cost

- `{cost}`: Defines the **acquisition cost** of an asset. It is part of the inventory lot itself and is used for booking reductions and calculating capital gains.
- `@ price`: An annotation that records a **market price** at the time of a transaction. It is used for currency conversions or to note the market value on a particular date.

Here are the three scenarios:

1. **Price Annotation (Conversion)**: Use `@` to convert from one currency to another.

   ```bean
   Assets:Forex     1000 USD @ 0.85 EUR
   ```

2. **Cost Basis (Acquisition)**: Use `{}` when buying an asset to establish its cost.

   ```bean
   Assets:Invest    10 STOCK {100.00 USD}
   ```

3. **Both (Sale with Price Record)**: When selling an asset, use `{}` to identify the lot being sold and `@` to record the sale price. This allows for automated capital gains calculation.

   ```bean
   Assets:Invest    -10 STOCK {100.00 USD} @ 105.00 USD
   ```

   This entry sells 10 `STOCK` from the lot that cost $100.00 each, at a sale price of $105.00 each.

A standalone `price` directive supplies reference data for market valuation. [Live Prices](https://beancount.io/docs/live-prices) can maintain these directives for supported assets in hosted ledgers. A refresh leaves your lots, booking method, acquisition costs, and recorded sale proceeds unchanged.

### Price Usage Rules

1. Price annotations (`@`) **do not** affect which lot is booked. Lot matching is handled exclusively by the cost basis (`{}`) and the account's booking method.
2. The `@` symbol is used only for:

- Currency conversions.
- Recording the market value of an asset at the time of a transaction.
- Providing the sale price for capital gains calculations.

## Configuration

You can configure booking methods globally or on a per-account basis.

### Global Booking Method

You can set a default booking method for your entire Beancount file using the `option` directive.

```bean
option "booking_method" "STRICT"
```

The accepted values are `"STRICT"` (the default when you set nothing), `"STRICT_WITH_SIZE"`, `"NONE"`, `"FIFO"`, `"LIFO"`, `"HIFO"` and `"AVERAGE"`. Any other string is rejected at load time with `Error for option 'booking_method'`. `"AVERAGE"` is accepted here and on `open`, but booking a reduction under it fails, as the **AVERAGE** section above shows.

### Per-Account Override

It's often useful to have different methods for different accounts. For example, you might want `FIFO` for a retirement account but `STRICT` for a taxable brokerage account to ensure you are selling specific tax lots. You can set the booking method when you open the account.

```bean
2024-01-01 open Assets:Retirement:401K "FIFO"
2024-01-01 open Assets:Taxable:Stock  "STRICT"
```

## Best Practices

1. **Inventory Organization**: To keep your ledger clean and simple, it is highly recommended to use separate accounts for each unique commodity you hold, and to constrain each one to that commodity on its `open` directive.

   ```bean
   ; GOOD: separate accounts by commodity, each constrained to one
   2024-01-01 open Assets:Invest:VTSAX  VTSAX
   2024-01-01 open Assets:Invest:VFIAX  VFIAX
   ```

   Avoid mixing different stocks or funds in the same account, as it complicates inventory management. The commodity list on `open` makes Beancount reject a stray posting instead of silently mixing two inventories.

2. **Lot Management**:

- Use meaningful labels for lots, especially for specific transactions like [tax-loss harvesting](https://beancount.io/docs/Solutions/cryptocurrency-portfolio-tracking) or employee stock grants.

  ```bean
  Assets:Invest:STOCK  10 STOCK {100.00 USD, "tax-loss-harvest-2024"}
  ```

- Document your trades with comments. This makes your ledger easier to read and understand later.

  ```bean
  Assets:Invest:STOCK  -10 STOCK {100.00 USD} @ 110.00 USD ; Gain: 10%
  ```

3. **Debugging**: If you encounter errors or unexpected behavior, Beancount provides tools to inspect the state of your inventory.

- **Examine Inventory State**: Use `bea doctor context main.beancount 42` to inspect the transaction at line 42, including its postings and the affected account balances. Replace the filename and line number with the transaction you want to inspect.

  Replace `<LINENO>` with the line number just after a transaction to see its effect.

- **Verify Lot Matching**: The `bea check` tool validates your entire file. It will catch any booking errors, such as ambiguous lot matches in `STRICT` mode.
