Support for per-posting payee

[hieu-van]

There are often cases that we might want to record payee on a per-posting basis. For example:

2024-1-2 an absurd transaction
        a:b:c                          $1     ; payee: Mr A
        a:b:c                          $2     ; payee: Mr B
        a:b:c                          $3     ; payee: Mr C
        wallet                        -$6

AFAIK this is possible with Ledger, but not with hledger. To achieve this, we can use a custom tag for recording payee, but that does come with its own limitations.

[simonmichael]

My 2c: this seems like a niche use case. When I have multiple payees, I usually feel separate transactions models that best. I have separate relationships/obligations with each of them which shouldn't be complected.

[hieu-van]

You are right. We should hear about the others' opinion on this

[pwseo]

While I agree this would be a niche feature, it still seems like a good one because one can already do the same with the date: posting tag (it would feel more consistent if it were possible to do so with a payee: tag as well).
Ledger compatibility would also be a nice bonus.

[simonmichael]

Consistency is a nice quality, but as de facto implementor/maintainer, (and given the level of complexity/legacy already in place,) you can probably understand if I'm reluctant to add complexity just for that, without solving practical problems.

Ledger compatibility is also nice but I have experienced that you can take that too far, we will never achieve 100% compatibility, and it is probably becoming less important for us over time.

But as always, a PR increases the chance that at least a few of us would give it a try.

[simonmichael]

Something to ask ourselves: does this exist in double entry bookkeeping ? Is it something professional bookkeepers do ?

[pwseo]

Simon, I agree with you:

• it probably makes more sense to split the transactions / it solves a single rarely occurring problem
• adding complexity can harm hledger's ability to thrive
• Ledger compatibility is less and less important
• there are much more important things to do with your (maintainer) time

I was just providing additional reasoning that I didn't think was explicit in the comments above :)

[savanto]

I have a slightly different usecase for this feature, which is arguably not so niche in small business bookkeeping:

My business has customers and issues invoices when work is completed:

2025-01-01 CustA
    asset:accounts receivable    $500.00
    revenue:sales

2025-01-01 CustB
    asset:accounts receivable   $1500.00
    revenue:sales

2025-01-01 CustC
    asset:accounts receivable   $1500.00
    revenue:sales

2025-01-01 CustD
    asset:accounts receivable   $4000.00
    revenue:sales

Payments get deposited (data imported from bank as CSV and processed):

2025-02-01 CustA | Deposit
    asset:bank                    $500.00
    asset:accounts receivable    $-500.00

2025-02-01 CustD | Deposit
    asset:bank                   $1000.00
    asset:accounts receivable   $-1000.00

I can build a neat report of customer balances with hledger bal 'asset:accounts receivable' --pivot payee:

            $1500.00  CustB
            $1500.00  CustC
            $3000.00  CustD
--------------------
            $6000.00

So far, so good. However, customers often pay by cheque, and cheques sometimes get deposited all together at the bank, so we may end up with an entry like

2025-02-01 ??? | Deposit
    asset:bank                   $3000.00
    asset:accounts receivable   $-3000.00

This also frequently happens when multiple customers pay by credit card in the same day, and the card processor makes only a single aggregated payout into the bank account once per day.

Now the customer balances look like this:

           $-3000.00  ???
            $1500.00  CustB
            $1500.00  CustC
            $3000.00  CustD
--------------------
            $3000.00

The total is correct, of course, but this report cannot distinguish who paid their invoices and who has not. I know, however, and I'd like to be able to "annotate" the journal entry like so:

2025-02-01 ??? | Deposit
    asset:bank                   $3000.00
    asset:accounts receivable   $-1500.00  ; payee:CustB
    asset:accounts receivable   $-1500.00  ; payee:CustC

and get a report like:

            $3000.00  CustD
--------------------
            $3000.00

(I do this annotation on imported bank data via a pre- and post-processing import pipeline that allows me to extend, merge, or completely replace certain transactions according to rules and "errata" journals that I maintain manually).

Workarounds

I have tried all of the following workarounds at some point in the past 12 months, which all work, but have tradeoffs (from a bookkeeping point of view, rather than from a hledger-software-maintenance point of view):

1. Split the postings into their own transactions, so the above double deposit transaction becomes:

2025-02-01 CustB | Deposit
    asset:bank                   $1500.00
    asset:accounts receivable

2025-02-01 CustC | Deposit
    asset:bank                   $1500.00
    asset:accounts receivable

Main problem with this: imported data look too different from raw data (more than 1 journal entry per 1 CSV entry; sometimes there are 10+!) and this can be confusing when comparing bank statements with the output of areg and similar. It's not clear that both transactions belong to 1 row of data.

2. Another approach is to give each customer their own account:

2025-01-01 CustA
    asset:accounts receivable:CustA    $500.00
    revenue:sales

...

2025-02-01 ??? | Deposit
    asset:bank                          $3000.00
    asset:accounts receivable:CustB    $-1500.00
    asset:accounts receivable:CustC    $-1500.00

Then you don't even need to --pivot, just the bal account filtered on accounts receivable produces the right report:

            $3000.00  asset:accounts receivable:CustD
--------------------
            $3000.00

I have two problems with this approach:

• Data duplication: each customer is both a payee and an account. This isn't terrible, but I've found that in practice it leads to extra work to annotate both fields, which leads to higher chance of mistakes. I could forgo the payee annotations, since the account specifies the customer, but then reports like areg 'asset:accounts receivable are less detailed.
• Another minor but annoying thing is that it becomes harder to provide an accountant with a 'trial balance' of the entire ledger, since it's polluted by an account for every customer the business has ever had. (I'm aware of the --tree and --depth options, so it's not impossible, but annoying and harder than just hledger bal).

3. Finally, I've tried giving each posting a special tag, like this:

2025-01-01 CustA
    asset:accounts receivable    $500.00  ; customer:CustA
    revenue:sales

...

2025-02-01 ??? | Deposit
    asset:bank                    $3000.00
    asset:accounts receivable    $-1500.00  ; customer:CustB
    asset:accounts receivable    $-1500.00  ; customer:CustC

hledger bal 'asset:accounts receivable' --pivot customer:

            $3000.00  CustD
--------------------
            $3000.00

This of course works just fine, but shares the same exact data duplication issues as (2). This is probably the approach I will settle on if I'm unable to reuse the payee field/tag, though the latter would be preferable.

In other words, I'd like to add as little extra data as possible (thereby doing as little extra work as possible), so overriding the payee field for select transactions would be neat.

---

One other workaround/approach I haven't tried yet, is to hook into journalTransform in a custom hledger extension command (eg. hledger-customerbalance), which would implement custom pivot rules. I'm not sure how feasible this is, but I could give this a shot if we really don't want to mess with tag/field precedence.

Lastly, maybe there's some other approach I'm overlooking?

---

How to implement

The ability to override a field name with a tag of the same name is a simple change (implemented in #2418):

diff --git a/hledger-lib/Hledger/Data/Journal.hs b/hledger-lib/Hledger/Data/Journal.hs
index 2d05de113..387901074 100644
--- a/hledger-lib/Hledger/Data/Journal.hs
+++ b/hledger-lib/Hledger/Data/Journal.hs
@@ -1147,6 +1147,7 @@ pivotAccount fieldortagname p =
 -- Pivoting on a tag when there are multiple values for that tag, returns the first value.
 pivotComponent :: Text -> Posting -> Text
 pivotComponent fieldortagname p
+  | Just (_, tagvalue) <- postingFindTag fieldortagname p = tagvalue
   | fieldortagname == "code",        Just t <- ptransaction p = tcode t
   | fieldortagname `elem` descnames, Just t <- ptransaction p = tdescription t
   | fieldortagname == "payee",       Just t <- ptransaction p = transactionPayee t
@@ -1156,7 +1157,6 @@ pivotComponent fieldortagname p
   | fieldortagname `elem` commnames = case map acommodity $ amounts $ pamount p of [s] -> s; _ -> unknown
   | fieldortagname == "amt"         = case amounts $ pamount p of [a] -> T.pack $ show $ aquantity a; _ -> unknown
   | fieldortagname == "cost"        = case amounts $ pamount p of [a@Amount{acost=Just _}] -> T.pack $ lstrip $ showAmountCost a; _ -> unknown
-  | Just (_, tagvalue) <- postingFindTag fieldortagname p = tagvalue
   | otherwise = unknown
   where
     descnames = ["desc", "description"]   -- allow "description" for hledger <=1.30 compat

This of course allows any tag named the same as a field to take precedence. If we want to limit this to just the payee field, that wouldn't be hard either.

[simonmichael]

Great discussion, and thanks for the PR.

I'm not convinced the benefit justifies the potential cost though.

I believe your solution 2, giving each customer their own account, is the natural one. Yes there is a little bit of duplication between description and account name - but not entirely, because these serve different purposes (accurate real world person/business name; convenient short category name).

And this is the kind of change with high risk of causing new complexities/problems which we might find months or years later. At minimum, we'd need to consider each possible overrideable field, and the implications of overriding each one.

[savanto]

accurate real world person/business name; convenient short category name

This is an interesting point I hadn't really considered. However I've realized that the big issue isn't the duplication (which is minor, I agree). The issue for me (in a business context) is producing reports for external accountants in a format and with data that they will find easy to work with, in which case the account name, or whatever is used as the pivot, should in fact be the real world entity name in the report, not a convenient short category name. (I think I classified working with external accountants as a "minor" issue in my original post, but it has since become the primary one!)

I've solved this problem for myself for now within a narrow context (per-customer aging summary report) by writing a custom hledger extension with my own tag-overriding-field logic. And in general I've found that I can customize behaviour to my needs by either extending hledger, or post-processing the CSV/JSON output. So I'm ok to table this change if it's not desirable.

high risk of causing new complexities/problems

I do agree that the potential for breaking existing setups in confusing ways is high, so it probably doesn't make sense as global change. Would you consider a flag/configuration-based implementation instead? Eg. --tags-override-fields (can be put into hledger.conf, or a compile-time flag, etc). I'm not sure what hledger's policy is for adding such things.

consider each possible overrideable field

I wouldn't go this route, this would be even more confusing to users (having to remember which fields are "special", rather than a consistent rule like "fields precede tags" or "tags precede fields").