Business Features Issues

From GnuCash
Jump to: navigation, search

The GnuCash business features are a set of tools layered on top of the basic accounting functionality in gnucash. It uses dedicated Accounts Receivable (AR) and Accounts Payable (AP) accounts to manage business transactions (invoicing/billing/payments).

In principle these AR/AP accounts are not meant to be manipulated directly. Yet gnucash does not prevent direct manipulation because sometimes a manual intervention is needed to keep the books correct. Unfortunately this "not meant to, yet allowed" configuration can lead to confusion and people mistakenly make changes in these accounts that go unnoticed by the business features.

Fortunately these changes will not throw off your books. The balances will still be correct as will be income statements and most other general accounting reports. The business features however as well as several business-specific reports will be off.

As a general rule of thumb don't create new transactions directly into an AR/AP account or create transactions in other accounts and which have one or more splits in an AR/AP account. These transactions will be ignored by the business features.

Apart from direct user entry in AR/AP accounts bugs in the gnucash software could also lead to unwanted links between invoices/bills and payments. The lot links which were introduced in gnucash 2.6.0 for example could lead to chains of transaction splits in the AR/AP account which could make it very difficult to figure out which invoice got paid by which payment or even which invoices were still (partly) unpaid.

This wiki page will list some common issues and offer methods to correct them.

Note the text below sometimes refers to bills/vendors and sometimes to invoices/customers. Unless explicitly stated the explanation is valid for both types of business objects. In case of vendors and bills the relevant account is always AP in case of customers it is AR. Adapt the steps below according to your needs to either set.

Unposting and reposting a paid invoice loses its payment

As of gnucash 2.6.0, when you unpost a paid invoice (or bill) and then repost it again after making corrections the invoice is no longer marked as paid. These have to be manually linked together again.

Unfortunately gnucash 2.6.0 to 2.6.2 contained bugs that prevented this. In those versions your only option is to

  • delete the payment
  • delete the accompanying lot link transaction from the AR account
  • reapply the payment

This is cumbersome so the recommended alternative is to upgrade to gnucash 2.6.3 or higher. As of that version here is how you can fix this

  • Open Business->Customer->Process Payment...
  • Select the correct customer and optionally also the correct "Post To" account (usually the latter is ok by default)
  • Now select both the unpaid invoice and the corresponding pre-payment
  • This should set the amount to 0 and the transfer accounts should get greyed out
  • Click Ok

If the amount is not 0 that means the unpaid amount of the invoice doesn't match the amount of the pre-payment. How to proceed depends on the situation.

  • Perhaps there was a second pre-payment to select ? You can do so and with all the lines selected click Ok.
  • Or the invoice wasn't fully paid before either ? Then manually set the amount to 0 to indicate no additional payment (apart from the pre-payment) should be entered now.
  • Or you have an additional payment to enter at this time ? You can set the amount to that of the additional payment and indicate which account was used for this payment.

Swamped in lot link transactions

As said above, as of version 2.6.0 gnucash can create lot link transactions in your AR/AP accounts. These particular transactions were introduced to allow the implementation of credit notes. Unfortunately the initial implementation used lot link transactions for each and every invoice payment, causing the AR/AP acounts to be flooded with lot link transactions.

As of gnucash 2.6.5 the lot link code has been considerably improved and will only be used when absolutely needed (which is when you offset an invoice with a credit note). If you used the business features of gnucash versions 2.6.0 to 2.6.4 your book will likely still have several superfluous lot links though.

To get rid of the superfluous lot link transactions you can

  • Go to your Account Hierarchy tab
  • Select "Actions -> Check & Repair -> Check & Repair All


  • Depending on the size of your financial data this can take a considerable amount of time. On my 2011 hardware running Fedora Linux, running Check & Repair on a book with 6328 splits in AR/AP combined it took almost 15 minutes to complete. I expect it to be much slower still on Windows.
  • More importantly there is still a bug in Check & Repair in GnuCash 2.6.5 that will cause it to end up in an infinite loop under certain conditions and the Check & Repair option will never finish. This bug will be fixed in GnuCash 2.6.6.
  • If you want to try and clean your book already in gnucash 2.6.5, please try this first on a copy. To know whether it is still performing normally or got into the infinite loop, you can open the transaction log file that is generated while gnucash is running Check & Repair. This transaction log is found in the same directory as your gnucash data file and has the .log extension. There will be several, you'll want to open the most recent one. The log lists the splits of transactions as they are being edited in blocks between '===== START' and '===== END' markers. If the same block gets repeated over and over again (note the posted date,descriptions and amounts) with each time more splits getting added you are in the endless loop. Your only way out is to kill gnucash and revert to your original copy.

Advanced manual intervention

If you run into the infinite loop but don't want to wait for gnucash 2.6.6 to clean up your lot link transactions here is what you can do (again - try this first on a copy):

  • From the log file generated during the infinite loop determine which transaction is causing the infinite loop. You can use the date posted, amounts and description as hints.
  • In the (fresh) copy of your data file, locate the transaction in your AR or AP account. This should be a lot link transaction.
  • Delete this transaction.
  • Any invoices/bills and payments this transaction linked together will now be unlinked. That means for this customer or vendor you will now have an unpaid invoice of bill again and one or more prepayments.
  • You can use the Business->Customer/Vendor->Process Payment... menu option to link these together again as described above.
  • Save your book and retry to run Check & Repair. It may run to completion now. Or it may end up in yet another infinite loop in which case there is yet another bad condition lot link transaction. So continue to repeat these steps until all these bad condition lot link transactions have been manually eliminated.

I entered a payment directly instead of using Process Payment

If you entered a payment transaction directly in the account registers (for example in your Checkings Account with a transfer to the Accounts Payable account), this transaction will be ignored completely by the business functions. That is probably not what you want. It won't show up on the Vendor Report nor in the Payment Window for your Vendor.

To integrate this transaction in the business features do this:

  • Open your Checkings Account (or whichever account this transaction was entered in)
  • Right-click on the transaction and select "Assign as payment..."
  • A Process Payment window will open with most of the payment's details filled in
  • Select the correct vendor
  • Optionally select a bill to pay. If you don't the payment will be treated as a pre-payment which you can assign to a bill in the future.
  • Click Ok


The logic behind "Assign as payment..." has to figure out if the payment is meant for a vendor's bill or a customer's invoice. The algorithm to determine this is quite basic and may propose the wrong business partner type. If that is the case unfortunately you can't use "Assign as payment..." for this transaction. Instead you will have to delete the transaction and use Business->Vendor->Process Payment..." to re-enter the payment in the traditional way.

Our bug tracker carries an enhancement request to improve on this situation.

What about importing payments from digital bank statements ?

If you use gnucash' import features to import banks statements these may also contain payments for business transactions. The imports have no connection with the business features so you can't directly pay invoices while importing. Instead you can import them as any other transaction and after the import use "Assign as payment..." as described above to get the payments recognized by the business features.

How can I see which transactions/splits are ignored by the business features ?

The above examples assume you are aware of a specific directly entered transaction. Maybe there are others which you didn't know of or have forgotten about. Perhaps you did enter such a transaction a long time ago, unaware this should not be done, or gnucash' autocomplete feature created such a transaction while you didn't notice. Or you have imported payments which you forgot to assign as payments after the import.

You can find all ignored transactions as follows:

  • Open your Accounts Payable account
  • Select Actions->View Lots
  • This will open a window with two panes. The tricky part is that there are two more panes which are hidden and which should get revealed. Somewhere slightly above the buttons at the bottom of the window is a horizontal slider handle. Drag this slider upwards for two more panes.
  • The bottom left pane is what interests us right now. It lists all splits in the AP account that are ignored by the business features.

Go over each split in this list and figure out what you want to do with it.

Each split that was intended as a payment can be corrected as follows:

For each split that was intended as a bill do this:

  • Make note of the full bill transaction details
  • Delete the split's transaction
  • Use Business->Vendor->Create Bill... to recreate the bill

I have some directly entered transactions in my AR I don't want to create real customers/invoices/payments for via the business features

These could for example be one-off business transactions. Creating a customer for it and then entering the invoice and then the payment still is just too cumbersome. And in the end the customer list is cluttered with customers you will never need again...

There are other ways of handling this than leaving directly entered transactions in the AR/AP accounts. You could for example create one generic customer and use that to track all one-off customer transactions. Just calls it "Other customers" or something like that.

If even that's too much work for you my advice still is to move these transactions to other accounts. For customer transactions you don't want to track with the business features, create an asset account with a name like "Other Accounts Receivable" or something and use that instead of the AR account for these transactions. For vendors you can create a liability account with a name like "Other Accounts Payable". In any case it's best to keep no directly entered transactions in the AR/AP accounts. In other words the list of "Free splits" in the Lot Viewer as explained above should be empty for your AR/AP accounts.

My payments are not applied to the correct invoices

You typically notice this when you want to process a payment for a customer and don't find the invoice with the expected amount. Instead there are other open invoices and perhaps a whole bunch of pre-payments in various directions.

This can happen if you frequently unpost and repost invoices again. Especially in gnucash version 2.6.0 to 2.6.4 where lot link transactions were intensely used.

Note GnuCash can be configured to automatically assign payments to invoice on invoice posting and during payment. In what follows we will be directly controlling which payment should go with which invoice. So on order to avoid the automatic assignment from interfering it is highly advised to disable Edit->Preferences->Business->Process Payment on posting for Invoices and/or Bills. It can be re-enabled afterwards if you like.

To get this fixed it is strongly advised to first get the superfluous lot link transactions cleaned up. Read #Swamped in lot link transactions to learn how to do that.

Once that is done there are several tools you can use in combination to find wrongly applied payments.

If you want to know the payment details on a particular invoice

  • Open the invoice in a report. There are many ways to get there. For example
  • Business->Customer->Find Invoice - Open the invoice - Print Invoice
  • Reports->Business->Customer Report - Select customer - Click on link for the right invoice - Print Invoice
  • Reports->Business->Invoice - Enter invoice number
  • In all cases you will want to adjust the report options to also display payments
  • You can read the date and amount for each payment from the report
  • You can use this information to make further corrections as explained later on

If you want a list of all invoices that are not fully paid yet

  • Open Business->Customer->Find Invoice...
  • Search for "Is paid" "Is "False"

To get an overview of unpaid invoices/open pre-payments for a given customer

  • Open Business->Customer->Process Payment...
  • If you don't want to make any changes, you can close this window again by clicking Cancel

Now, imagine you have found a payment that is not applied to the correct invoice for whatever reason and want to correct this. This is a multi-step process.

  • First open the Process Payment window
  • Select the proper customer
  • Check if the invoice is still in the list of unpaid invoices. It doesn't matter if the open amount is not the full payment amount, but it should be in the list.
  • If the invoice is no longer in the list that means another payment has already been applied. This must first be undone. To do so
  • Use Business->Customer->Find Invoice to find the invoice
  • Unpost the invoice and repost it again. In gnucash 2.6.x this will untie the invoice and the payment


If there were still other payments linked to this invoice these payments will be (partly) undone. That should be expected because if you are correcting this invoice's payment chances are the other payments to this invoice were also wrong. So you need to iterate this process:

  • After you have corrected this invoice reopen the Process Payment window for this customer
  • Look at what changed:
  • a new unpaid invoice: find it's proper payment (if the customer really did pay the invoice already) and do the same thing
  • a new pre-payment: use the tools above to figure out which invoice it really should be applied to and start over for this payment/invoice pair
  • Continue iterating until all the invoices/pre-payments are cleaned up. That means either there are no invoices/payments left in the Process Payment window or those that are still there match your accounting reality (some invoices may still be due, or some pre-payments are really waiting for an invoice).
  • If needed repeat for other customers and vendors.