Posting Specification¶

A posting represents a single line item within a transaction, recording a change to an account's balance.

Syntax¶

    [STATUS] ACCOUNT  [AMOUNT] [@ PRICE | @@ TOTAL] [= BALANCE] [; COMMENT]

Components¶

Indentation¶

Postings MUST be indented:

2024-01-15 Transaction
    Expenses:Food    $50.00     ; Indented with spaces
    Assets:Checking            ; Indented with tab

Minimum: 1 space or 1 tab. Convention: 2-4 spaces.

Account¶

The account being affected:

    Expenses:Food:Groceries    $50.00
    Assets:Bank:Checking      $-50.00

Amount¶

The quantity and commodity:

    Expenses:Food     $50.00        ; Positive
    Assets:Checking  $-50.00        ; Negative
    Assets:Stock      10 AAPL       ; Shares
    Assets:Checking                 ; Elided (calculated)

Price Annotation (@)¶

Per-unit market price:

    Assets:Stock    10 AAPL @ $150.00
    ; 10 shares at $150 each

Total Price (@@)¶

Total price for all units:

    Assets:EUR    100 EUR @@ $110.00
    ; 100 EUR for $110 total

Balance Assertion (=)¶

Assert balance after posting:

    Assets:Checking    $100 = $1500
    ; Balance must be $1500 after

Balance Assignment¶

Set balance to specific value:

    Assets:Checking    = $1500
    ; Set balance TO $1500, infer amount

Comment¶

End-of-line comment:

    Expenses:Food    $50.00  ; Weekly groceries

Amount Elision¶

One posting per commodity can omit amount:

2024-01-15 Transaction
    Expenses:Food    $50.00
    Assets:Checking          ; Calculated as $-50.00

Multiple Commodities¶

2024-01-15 Multi-currency
    Assets:EUR    100 EUR
    Assets:USD              ; Elided USD amount
    Expenses:Fees    5 EUR

Elision Rules¶

Only ONE posting per commodity can be elided
Elided amount is calculated to balance transaction
Error if transaction cannot balance

Balance Assertions¶

Single-Commodity Assertion (=)¶

    Assets:Checking    $100 = $1500
    ; After this posting, USD balance is $1500

Subaccount-Inclusive Assertion (=*)¶

    Assets:Bank    $0 =* $5000
    ; Assert Assets:Bank plus all subaccounts = $5000

Zero Assertion¶

    Assets:Checking    $0 = $0
    ; Confirm account is empty

Balance Assignments¶

Set Balance¶

2024-01-15 Reconciliation
    Assets:Checking    = $1234.56
    ; Calculate amount needed to reach $1234.56
    Equity:Adjustments

With Amount¶

2024-01-15 Deposit
    Assets:Checking    $500 = $1734.56
    ; Add $500, assert new balance is $1734.56
    Income:Gift

Virtual Postings¶

Unbalanced Virtual (Parentheses)¶

    (Budget:Food)    $-50.00
    ; Not included in balance

Balanced Virtual (Brackets)¶

    [Savings:Goal]    $-50.00
    ; Must balance with other [] postings

Example¶

2024-01-15 Expense with Budget
    Expenses:Food        $50.00    ; Real
    (Budget:Food)       $-50.00    ; Virtual unbalanced
    Assets:Checking     $-50.00    ; Real

2024-01-15 Savings Allocation
    Assets:Checking      $100.00   ; Real
    [Savings:Emergency]  $-50.00   ; Virtual balanced
    [Savings:Vacation]   $-50.00   ; Virtual balanced
    Income:Salary                  ; Real

Posting Metadata¶

Comments¶

    Expenses:Food    $50.00  ; Receipt #1234

Tags¶

    Expenses:Food    $50.00
        ; category:groceries, location:downtown

Multi-Line Metadata¶

    Expenses:Food    $50.00
        ; vendor:Whole Foods
        ; receipt:IMG_001.jpg

Posting Status¶

Status can be on individual postings:

2024-01-15 Mixed Transaction
    * Expenses:Food    $30.00    ; Cleared
    ! Expenses:Misc    $20.00    ; Pending
    Assets:Checking

Posting Dates¶

Using Tags¶

    Expenses:Bill    $100  ; date:2024-01-20

Bracket Syntax¶

    Expenses:Bill    $100  ; [2024-01-20]

Secondary Date¶

The posting date overrides transaction date for this posting in date-filtered reports.

Two-Space Rule¶

At least two spaces (or a tab) required between account and amount:

    Expenses:Food  $50.00    ; Correct: 2 spaces
    Expenses:Food $50.00     ; WRONG: parsed as "Expenses:Food $50.00"

Account Separators¶

    Assets:Bank:Checking    ; Colon-separated

Whitespace Handling¶

Leading whitespace: Required for posting (indent)
Account/amount separator: 2+ spaces or tab
Trailing whitespace: Ignored

Validation Rules¶

Account required - Every posting needs an account
Amount optional - Can be elided if calculable
Indentation required - Must be indented
Two-space separation - Between account and amount
Balance assertions - Checked at parse time

Examples¶

Simple Posting¶

    Expenses:Food    $50.00

With Balance Assertion¶

    Assets:Checking    $100 = $1500

Virtual with Metadata¶

    (Budget:Food)    $-50.00
        ; category:variable
        ; period:monthly

Stock Purchase¶

    Assets:Brokerage:AAPL    10 AAPL @ $150.00

Complete Example¶

2024-01-15 * Grocery shopping
    ; trip:weekly
    Expenses:Food:Groceries    $75.00
        ; store:Whole Foods
    Expenses:Food:Snacks    $15.00
    (Budget:Food)    $-90.00
    Assets:Checking    = $1234.56
        ; reconciled:true