Transaction Directive¶
Transactions are the primary entries in an hledger journal, recording financial movements between accounts.
Syntax¶
DATE [=DATE2] [STATUS] [CODE] DESCRIPTION
POSTING
POSTING
...
Components¶
Date (Required)¶
2024-01-15 Transaction with dashes
2024/01/15 Transaction with slashes
2024.01.15 Transaction with dots
Secondary Date (Optional)¶
The = separates primary and secondary dates:
2024-01-15=2024-01-20 Payment with effective date
Expenses:Bill $100
Assets:Checking
- Primary date: Transaction entry date
- Secondary date: Effective/posting date
Status (Optional)¶
2024-01-15 Unmarked transaction
...
2024-01-15 ! Pending transaction
...
2024-01-15 * Cleared transaction
...
| Marker | Meaning | Description |
|---|---|---|
| (none) | Unmarked | Not yet reviewed |
! |
Pending | Entered but awaiting confirmation |
* |
Cleared | Verified/reconciled |
Code (Optional)¶
Check number or reference in parentheses:
2024-01-15 (#1234) Check payment
Expenses:Rent $1500
Assets:Checking
2024-01-15 (INV-001) Invoice payment
Assets:Receivable $500
Income:Sales
Description (Required)¶
Free-form text describing the transaction:
2024-01-15 Grocery shopping at Whole Foods
Expenses:Food $75
Assets:Checking
2024-01-15 Monthly rent payment
Expenses:Housing:Rent $1500
Assets:Checking
Postings (Required)¶
At least one posting required. See Posting Specification.
Minimum Transaction¶
2024-01-15 Description
Account:One $50
Account:Two
Complete Example¶
2024-01-15=2024-01-20 * (#1234) Monthly rent payment
; tag:housing, recurring:monthly
Expenses:Housing:Rent $1500.00
; landlord:ABC Properties
Assets:Checking $-1500.00 = $3500.00
; check:cleared
Transaction Comments¶
Header Comment¶
2024-01-15 Transaction ; This is a header comment
Expenses:Food $50
Assets:Checking
Transaction-Level Tags¶
After description or on next indented comment line:
2024-01-15 Office supplies ; project:renovation, dept:ops
Expenses:Office $100
Assets:Checking
2024-01-15 Conference travel
; trip:annual-conf
; approved-by:manager
Expenses:Travel $500
Assets:Checking
Multi-Posting Transactions¶
2024-01-15 Split expense
Expenses:Food:Groceries $50.00
Expenses:Food:Snacks $10.00
Expenses:Household $25.00
Assets:Checking $-85.00
Balancing Rules¶
- Sum to zero: All posting amounts must sum to zero
- One elision per commodity: One posting per commodity can omit amount
- Automatic balancing: Elided posting gets calculated amount
Valid¶
2024-01-15 Balanced explicitly
Expenses:Food $50.00
Assets:Checking $-50.00
2024-01-15 Balanced with elision
Expenses:Food $50.00
Assets:Checking ; Inferred: $-50.00
Invalid¶
; ERROR: Does not balance
2024-01-15 Unbalanced
Expenses:Food $50.00
Assets:Checking $-40.00
Multi-Currency Transactions¶
2024-01-15 Currency exchange
Assets:USD $-100.00
Assets:EUR 90.00 EUR @@ $100.00
2024-01-15 International purchase
Expenses:Shopping 100.00 EUR @ $1.10
Assets:Checking $-110.00
Virtual Postings¶
2024-01-15 Expense with budget tracking
Expenses:Food $50.00 ; Real posting
(Budget:Food) $-50.00 ; Virtual unbalanced
Assets:Checking $-50.00 ; Real posting
Periodic Transactions¶
Template for forecasting (with ~):
~ monthly from 2024-01-01
Expenses:Rent $1500
Assets:Checking
Transaction Modifiers¶
Auto-posting rules (with =):
= expenses:food
(Budget:Food) *-1
; Applied to matching transactions
2024-01-15 Groceries
Expenses:Food $50
Assets:Checking
; Auto-adds: (Budget:Food) $-50
Status Inheritance¶
Transaction status can apply to postings:
2024-01-15 * Cleared transaction
Expenses:Food $50 ; Inherits cleared
Assets:Checking $-50 ; Inherits cleared
2024-01-15 Mixed status
* Expenses:Food $30 ; Explicitly cleared
! Expenses:Drink $20 ; Explicitly pending
Assets:Checking ; No status
Date Ordering¶
Transactions should be in chronological order:
2024-01-14 Earlier
...
2024-01-15 Later
...
hledger will warn if dates are out of order (with --strict).
Best Practices¶
- Use consistent date format (prefer YYYY-MM-DD)
- Include descriptive text for all transactions
- Mark status as transactions are reconciled
- Add relevant tags for reporting
- Keep transactions in date order
- Use balance assertions regularly
Examples¶
Simple Purchase¶
2024-01-15 Coffee shop
Expenses:Food:Coffee $5.00
Assets:Cash
Paycheck with Withholdings¶
2024-01-15 * Paycheck ; employer:ACME Corp
Assets:Checking $3,500.00
Expenses:Tax:Federal $700.00
Expenses:Tax:State $200.00
Expenses:Tax:FICA $300.00
Expenses:Benefits:Health $100.00
Income:Salary $-4,800.00
Investment Purchase¶
2024-01-15 Buy Apple stock
Assets:Brokerage:AAPL 10 AAPL @ $150.00
Expenses:Fees $9.99
Assets:Brokerage:Cash $-1509.99
Transfer Between Accounts¶
2024-01-15 * Transfer to savings
Assets:Savings $500.00
Assets:Checking $-500.00