I don't really know enough about the new features to document that.
If some-one can point me to this information if it already exists elsewhere or add some text to this bug, I'll try to include it in the Help. I won't add it to the Guide as long term I think it is generally agreed that the Guide should be merged into Help.

I will now document in the Help how to handle "Business invoices over/pre payments" from the discussion on gnucash-devel.

Created attachment 319714 [details] [review]
Add instructions for over payments

Review of attachment 319714 [details] [review]:

commit 1d8137c

I added an id to the section. Perhaps at some point it might be referenced. It seems section ids in this chapter have trailing the level.

2 question arise:
 If overpayment is allowed, how about partial payment?
 Also missing in section Payment is the more convenient way of marking (imported) transactions as payment.

I'll answer the questions in telegram style, which I hope is sufficient to convert in basic documentation:

Partial payments are possible too. Select the invoice to pay. Gnucash will automatically suggest that invoice's remaining balance as payment amount. Simply adjust that amount to what you want to pay.

As for the second question: this can best done starting from the asset account holding the imported payment transaction (like your bank account if you imported transactions from your bank statement).
In that account, select the payment, right-click and choose "Assign as payment...". The payment window will pop-up, partly filled in with the information from the transaction. Fill in the missing information like the proper vendor/customer and invoice/bill to complete the payment.

One caveat: the logic behind "Assign as payment..." won't properly detect credit note reimbursements and will wrongfully interpret such a transaction as a bill (for customer reimbursements) or an invoice (for vendor reimbursements).

Hi Frank and Geert, Thanks for the help. I'll look at this when I'm back Monday week.

Hi Geert,
Thanks, I'm including your answers.

I think I should also update the equivalent info re vendor bills.
Should I include in vendor payments the info re over/pre payments?
I'm not sure if there is a situation where anyone would intentionally overpay or prepay a bill...

(In reply to Chris Good from comment #6)
> Hi Geert,
> Thanks, I'm including your answers.
> 
> I think I should also update the equivalent info re vendor bills.
> Should I include in vendor payments the info re over/pre payments?
> I'm not sure if there is a situation where anyone would intentionally
> overpay or prepay a bill...

It may not be common all over the world. In my country however it's not uncommon for vendors to ask to pre-pay bills. They won't even send a genuine bill with the request. That bill will only be sent later (together with the ordered goods for example).

As for overpaying, that's unlikely to be done intentionally. However it can happen by accident. And in that case as well it's useful if a user finds information on how to model this in gnucash.

So I'm tempted to include the same information for vendors and bills.

Hi Geert,

Thanks for your advise above.

I'd also like to add some info to the Help from some assistance you gave on the gnucash-user mailing list January 8, 2016 3:31 AM.
Here is my interpretation of your words. I'd really appreciate it if you could review it.

How to Write Off a Bad Debt
===========================

Note: Please check with your accountant to ensure the following is acceptable in your region.

The proper way to do this is to process a payment for the invoice to a "BadDebt" account.
Such an account would be an expense account. However, in GnuCash, you can't process a payment for an invoice directly to an expense account.
So it takes two steps:
 1. Pay the invoice to an asset or liability account, such as your checking account.
 2. Change the asset or liability account, in the NON Accounts Receivable split of the payment transaction, to the BadDebt expense account.

Specifically
1. If you have already unsuccessfully tried to account for the bad debt, remove any lotlink transactions and any related transactions (that is: payments), including any transaction between your BadDebt and A/R for the invoice. If all is well, your "Process Payment" window for this customer should list the invoice the customer won't pay, and no prepayments.
2. Pay your invoice to an arbitrary asset or liability account. It can be your checkings account. We will fix that in the next step.
3. Open the account register for your A/R account. For this invoice there should now be one lotlink transaction and one payment transaction.
4. Select the payment transaction and change the transfer account to be your "BadDebt" account. Make sure to leave the transaction (eg by clicking on another transaction) to save the changes.
5. If all is well, your "Process Payment" window should still be clean: no pre-payments, and the bad debt invoice gone.

Note: Some version of gnucash before 2.6.6 still make extensive use of lotlinks. This comes with its own set of subtle issues. It is suggested to upgrade to the latest (or at least version 2.6.6), which fixes a lot of small problems. Once upgraded, please run "Check & Repair" on your A/R and A/P accounts to clean up most of the lotlink legacy. Don't forget to make a backup first just in case.

See also : http://wiki.gnucash.org/wiki/Correcting_Business_Transaction_Mistakes

Chris,

Thank you for converting my assistance into proper help documentation.

Aside from a few details what you have written is correct.

It gets a bit blurry with regards to the lot links issue so let me give you some background on this.

When I wrote my reply on the list it was tailored to gnucash version 2.6.3 (and valid for any version between 2.6.0 and 2.6.4). These versions exposed a nasty implementation detail in the form of lot link transactions. These transactions would appear in A/R and A/P registers for each posted invoice and each payment. In many (most even) cases they were superfluous and I fixed the code in 2.6.5. So as of that version these lot link transactions are only created when absolutely necessary. On the other hand lot link transactions that are already in the data are not automatically deleted. So even if you are currently using gnucash 2.6.11, you can still have lot links from the time you were using a version of gnucash between 2.6.0 and 2.6.4.

As a final word on these lot link transactions, most of them can be cleaned up automatically by running Check & Repair on your A/P or A/R accounts (as of gnucash 2.6.6).

Now back to your interpretation of my mail: I have added some clarifications/corrections below.

(In reply to Chris Good from comment #8)
> How to Write Off a Bad Debt
> ===========================
> 
> Note: Please check with your accountant to ensure the following is
> acceptable in your region.
> 
> The proper way to do this is to process a payment for the invoice to a
> "BadDebt" account.
> Such an account would be an expense account. However, in GnuCash, you can't
> process a payment for an invoice directly to an expense account.
> So it takes two steps:
>  1. Pay the invoice to an asset or liability account, such as your checking
> account.
>  2. Change the asset or liability account, in the NON Accounts Receivable
> split of the payment transaction, to the BadDebt expense account.
> 
> Specifically
> 1. If you have already unsuccessfully tried to account for the bad debt,
> remove any lotlink transactions and any related transactions (that is:
> payments), including any transaction between your BadDebt and A/R for the
> invoice. If all is well, your "Process Payment" window for this customer
> should list the invoice the customer won't pay, and no prepayments.

Given that current versions of gnucash don't create lot link transactions any more, I would only mention them as an afterthought, not as first item in the list of things to remove. So rather make this something like
... remove all transactions from the A/R account related to the invoice, except for the invoice's transaction itself. This inclucdes any payment transactions, transactions between your BadDebt and A/R account. In case the payment has associated lot link transactions (1), remove those as well. ...

The (1) can refer to the note below where you briefly explain the possible existence of lot link transactions and their issues.

> 2. Pay your invoice to an arbitrary asset or liability account. It can be
> your checkings account. We will fix that in the next step.
> 3. Open the account register for your A/R account. For this invoice there
> should now be one lotlink transaction and one payment transaction.

There won't be a lot link transaction any more, only a payment transaction in current versions of gnucash. This could become:

... For this invoice there should now be one payment transaction. Note: if you are using gnucash 2.6.0 - 2.6.4 there will also be one lot link transaction (1)) ...

Optionally again with a link to the note on lot link transactions.

> 4. Select the payment transaction and change the transfer account to be your
> "BadDebt" account. Make sure to leave the transaction (eg by clicking on
> another transaction) to save the changes.
> 5. If all is well, your "Process Payment" window should still be clean: no
> pre-payments, and the bad debt invoice gone.
> 
> Note: Some version of gnucash before 2.6.6 still make extensive use of
> lotlinks. This comes with its own set of subtle issues. It is suggested to
> upgrade to the latest (or at least version 2.6.6), which fixes a lot of
> small problems. Once upgraded, please run "Check & Repair" on your A/R and
> A/P accounts to clean up most of the lotlink legacy. Don't forget to make a
> backup first just in case.

The lot links were created by gnucash versions 2.6.0 to 2.6.4. I recommend however to upgrade to at least 2.6.6 because the logic in 2.6.5 to clean up the lot links was flawed and could create other issues.

> 
> See also :
> http://wiki.gnucash.org/wiki/Correcting_Business_Transaction_Mistakes

I hope this clarifies it sufficiently for you.

Hi Geert,

Thanks that is very informative.
I'm still a little uncertain about the usage of lots.

Are you saying that in the current GnuCash, assuming lot links have been cleaned up by ""Check & Repair", there will be no lot links linking invoices to payments/credit notes?

How does GnuCash handle multiple invoices paid with 1 payment, or 1 invoice paid with multiple payments?

Is there a "lot" and a "lot link" record (I say "record" for want of a better XML term to refer to the equivalent of a relational database row)?

(In reply to Chris Good from comment #10)
> Hi Geert,
> 
> Thanks that is very informative.
> I'm still a little uncertain about the usage of lots.

Lots have always been in use for relating payments to invoices. Lots themselves are invisible in the account registers. To see them you need to open the lot viewer, which can be found in the Actions menu under "View lots" for any AR or AP account.

Lot links on the other hand are *transactions* which you can see in your AR and AP accounts. They are unusual in the sense that all their splits are in one account (be it AR, AP). Each split in a lot link transaction is then "linked" (hence the name) to an invoice or payment transaction by means of a lot.

> 
> Are you saying that in the current GnuCash, assuming lot links have been
> cleaned up by ""Check & Repair", there will be no lot links linking invoices
> to payments/credit notes?

No. Internally a credit note is like an invoice (but of opposite sign) and the technical limitation we have is that a lot can only refer to one single invoice (or credit note). It can refer to multiple payments though.

And I should perhaps clarify that lots don't bundle transactions but splits and only splits from one AR account. Each payment transaction has one or more splits, some in your cash or bank accounts and at least one in your AR account. For the lot handling only the splits in the AR account are taken into consideration. The same goes for an invoice transaction. It can have multiple splits in for example income accounts, tax accounts and exactly one split in the AR account. Again only this split in the AR account is considered for the lot handling.

From all of this follows:

1. Normally paying an invoice can be handled with a lot, regardless of how many payments were used to pay the invoice.

2. Paying multiple invoices with one payment is a variation of the first option. In this case the payment transaction will have multiple splits in the AR account. Each split matches the amount that has been paid to one of the invoices. Handling the payment for each invoice is therefore reduced to creating one lot per invoice and each lot will link to one of the AR splits of the payment.

3. "Paying" (part of) an invoice with a credit note can't be handled with one lot because one lot can only refer to one single invoice or credit note. So in this case a lot link transaction will still be created as it's the only way to link the two together. Compared with the first implementation of lot link transactions (2.6.0-2.6.4) this transaction now clearly tells you which invoice and credit note it links together. So it should be slightly less mysterious and confusing.

So as you can see, lot links are not completely gone. They can't technically. But their use is greatly reduced (only where both an invoice AND a credit note are involved in one single business action), and should be clearer to read.

Lastly, check and repair will fix 90% of the redundant lot links. There are a few corner cases where lot links result in ambiguous situations (multiple ways to reduce the lot link). I have deliberately chosen not to assume one or the other solution in the check & repair code, but instead leave the lot link untouched. So even after running check & repair there may be a few lot links left that a user with understanding of the real world transaction could manually clean up. But even if the user chooses not to clean it up, the numbers would be correct, so it's usually not mandatory.

> 
> How does GnuCash handle multiple invoices paid with 1 payment, or 1 invoice
> paid with multiple payments?
> 

See above.

> Is there a "lot" and a "lot link" record (I say "record" for want of a
> better XML term to refer to the equivalent of a relational database row)?

Yes. Lots have their own xml entities, called "lot". As explained above, "lot links" on the other hand are just ordinary transactions. There is nothing special about them except they only serve to link invoices and credit notes (and payments in the older implementation). The linking itself is done via the lots though...


Perhaps it helps to think about a lot link transaction is as a special variant of a multi-split payment. Assume we have a credit note and and invoice both of $100. This would be expressed by these transactions:

Invoice:
Income                 $100
AR           $100

Credit note:
Income       $100
AR                     $100

We could have a payment for the invoice and have issued a reimbursement for the credit note. This would yield the following 2 transactions:

Invoice payment:
Bank         $100
AR                     $100

Credit note reimbursement:
Bank                   $100
AR           $100

Considering how the business logic works, there will also be two lots in the AR account for these transactions: one to link the invoice to its payment and one to link the credit note to its reimbursement.

Now as we have seen above, you could also pay multiple invoices with one payment. And if you remember a credit note is internally also considered an invoice (with opposite sign), I could process the payment of the invoice and the reimbursement of the credit note with one transaction. 

Combined payment for one invoice and one credit note:
Bank         $100                   -> invoice payment
AR                     $100         -> invoice payment
Bank                   $100         -> cn reimbursement
AR           $100                   -> cn reimbursement

Of course the bank splits seem a bit odd because no real money is moved around at all. Temporarily keeping these splits helps to see the link with independent payments though. We'll get back to this in a second.

As explained earlier, paying multiple invoices/credit notes will result in a payment with one split in the AR for each invoice/credit note to pay. Again there will be two lots: on linking the payment split with the invoice and one linking the reimbursement split with the credit note. So the AR splits, although they balance each other out can't be removed. Each separate split is used in a different lot.

As said in this situation there is not really any money moving around. This shows because the bank splits balance out as well. And since they are not used in a special way by gnucash (unlike the AR splits), we can remove them from the transaction, resulting in:

Combined payment for one invoice and one credit note:
AR                     $100         -> invoice payment
AR           $100                   -> cn reimbursement

And there you have the famous "lot link" transaction gnucash now has when balancing invoices with credit notes.

As you can see it's really an evolution of an ordinary payment transaction where payment and reimbursement balance each other out.

Hopefully this clears it out a bit more still.

Created attachment 324353 [details] [review]
Add Help Doc for invoice bad debt write offs

Thanks for the patch. I have committed it to maint, so it will appear for the next release.

I made one minor change - I renamed the wiki page you refer to just yesterday. So I updated the link in your patch.

Does this conclude the work for this bug report for you ? If so I will close it. If you intend to write something about matching payments from the importers still, I'll keep it open.

Review of attachment 324353 [details] [review]:

Committed

Hi Geert,

Thanks very much for the extra info re lots and updating the link.

Re: matching payments from the importers

Does that refer to just right clicking on a payment in a register and doing 'Assign as payment'? (this is already mentioned in Process Payment as a tip). If not, I don't know about it as I haven't imported any transactions.
If some-one can point me to something about this, I'm happy to include it in the documentation.

(In reply to Chris Good from comment #15)
> Re: matching payments from the importers
> 
> Does that refer to just right clicking on a payment in a register and doing
> 'Assign as payment'? (this is already mentioned in Process Payment as a
> tip). If not, I don't know about it as I haven't imported any transactions.
> If some-one can point me to something about this, I'm happy to include it in
> the documentation.

The main point IMO is there is no direct link between the import features and business features, so linking a imported payment with an invoice/bill is a two-step process.

The first being the import itself and then using the "Assign as payment" method you already added as a tip.

I don't know if this needs more details in the guide than you have already added and, in case you estimate it does, nor would I know which place would be the best to put it. In a chapter dedicated to the business features or rather in a chapter on importing ?

You can follow your own judgement here.

Created attachment 324772 [details] [review]
Extra note re Assign as payment

I agree with Geert it is worth noting that there is no way to link a payment to an invoice during importing, so here is an extra patch to maint for that.

GnuCash bug tracking has moved to a new Bugzilla host. This bug has been copied to https://bugs.gnucash.org/show_bug.cgi?id=729265. Please update any external references or bookmarks.