Payee Directive¶

The payee directive declares and validates payees (vendors, merchants).

Syntax¶

payee NAME
    [SUBDIRECTIVE...]

Examples¶

Basic Declaration¶

payee Whole Foods

With Subdirectives¶

payee Whole Foods
    alias WholeFds
    alias WHOLEFDS
    note Organic grocery store

With Account Mapping¶

payee Shell Gas Station
    alias SHELL
    alias Shell Oil
    uuid 12345
    note Gas station

Subdirectives¶

alias¶

Create alternative names for payee matching:

payee Whole Foods Market
    alias WHOLEFDS
    alias WFM
    alias "WHOLE FOODS"

; All of these match:
2024/01/15 WHOLEFDS #1234
    Expenses:Food    $87.50
    Assets:Checking

note¶

Add documentation:

payee Amazon
    note Online shopping - review for categories

uuid¶

Assign a unique identifier:

payee Acme Corp
    uuid client-001

Payee Matching¶

Ledger normalizes and matches payees:

payee Starbucks Coffee
    alias STARBUCKS
    alias "STARBUCKS STORE"

; These all match the same payee:
2024/01/15 Starbucks Coffee
2024/01/16 STARBUCKS
2024/01/17 starbucks
2024/01/18 STARBUCKS STORE #123

Account Association¶

In the account directive:

account Expenses:Food:Coffee
    payee ^(Starbucks|Peet|Blue Bottle)

Transactions with matching payees auto-categorize.

Regex Patterns¶

Use regular expressions for flexible matching:

payee Amazon
    alias /^AMZN/
    alias /^Amazon\.com/

2024/01/15 AMZN MKTP US*123
    ; Matches Amazon payee
    Expenses:Shopping    $50.00
    Assets:Checking

Unknown Payee Handling¶

With --strict or --pedantic:

ledger --strict -f journal.ledger

Undeclared payees generate warnings/errors.

Payee Reports¶

List Payees¶

ledger payees

Transactions by Payee¶

ledger reg @"Whole Foods"

Payee Statistics¶

ledger reg --group-by payee Expenses

Use Cases¶

Bank Import Cleanup¶

; Map bank descriptions to clean names
payee Whole Foods Market
    alias WHOLEFDS MKT
    alias WFM #
    alias "WHOLE FOODS"

payee Shell
    alias SHELL OIL
    alias SHELL SERVICE

payee Amazon
    alias AMZN MKTP
    alias AMAZON.COM
    alias AMZN.COM

Vendor Management¶

payee Acme Supplies
    uuid vendor-001
    note Office supply vendor
    ; Last order: 2024/01/15

payee Tech Solutions Inc
    uuid vendor-002
    note IT consulting

Expense Categorization¶

Combined with account directives:

account Expenses:Food:Groceries
    payee ^(Whole Foods|Trader Joe|Safeway|Costco)

account Expenses:Food:Coffee
    payee ^(Starbucks|Peet|Blue Bottle|Philz)

account Expenses:Transportation:Gas
    payee ^(Shell|Chevron|Exxon|BP|Costco Gas)

Querying by Payee¶

Exact Match¶

ledger reg @"Whole Foods"

Pattern Match¶

ledger reg @/Starbucks/

Combined Queries¶

ledger reg @"Whole Foods" and Expenses:Food

Best Practices¶

Declare common payees at file start
Add aliases for bank import variations
Use regex patterns for flexible matching
Document with notes for context
Combine with account payee subdirective

Example: Complete Payee Setup¶

; ===== Payee Declarations =====

; Groceries
payee Whole Foods Market
    alias WHOLEFDS
    alias WFM
    note Organic grocery store

payee Trader Joe's
    alias TRADER JOE
    alias TJ'S
    note Budget-friendly groceries

payee Costco
    alias COSTCO WHSE
    note Bulk shopping

; Coffee
payee Starbucks
    alias STARBUCKS STORE
    alias SBUX
    note Coffee and snacks

; Gas
payee Shell
    alias SHELL OIL
    alias SHELL SERVICE
    note Gas station

payee Chevron
    alias CHEVRON STATION
    note Gas station

; Online
payee Amazon
    alias AMZN MKTP
    alias AMAZON.COM
    alias AMZN.COM
    note Online shopping - check category

; ===== Account Mappings =====

account Expenses:Food:Groceries
    payee ^(Whole Foods|Trader Joe|Costco)

account Expenses:Food:Coffee
    payee ^(Starbucks)

account Expenses:Transportation:Gas
    payee ^(Shell|Chevron)

; ===== Transactions =====

2024/01/15 WHOLEFDS MKT #1234
    Expenses:Food:Groceries    $87.50
    Assets:Checking

2024/01/16 SHELL OIL 54321
    Expenses:Transportation:Gas    $45.00
    Assets:Checking