Billing Preferences

Billing Preferences

Back   Posted on 1 september 2018 / Updated on 28 june 2020
Reading time 9 minutes

Invoicing Mode

Billing Extension offers you 3 new billing modes:

If you are not interested in using any of these features, leave Legacy mode selected. It corresponds to default billing WHMCS. Please notice that billing modes can be used simultaneously. For example you can have OneInvoice for client X, OnePayment for Y, Manual for Z and use Legacy for all other customers.


In line with tax regulations, clients details and custom field data (for example VAT Numbers) will all be recorded and saved at the time an invoice or a proforma in generated. WHMCS already has a similar feature that serves this purpose but it's not ideal to use. First off WHMCS doesn't store all information and doesn't allow you to edit them. On the contrary Billing Extension stores everything relevant:

We also give you an interface from which administrators can easily edit snapshots and compare them with live values. This interface is integrated directly on every proforma, invoice or credit note and can also be used to manually take a snapshot.

Now that you know all the aspects covered by the module, we can describe you the difference between the options On Invoice Creation and On Proforma Creation. The first one takes snapshots when an invoice is issued while the latter as soon as a proforma is generated. Ideally you should use the first option so that a customer can update his personal details if he notices that there's a problem with them. His changes will have effects on all open proformas and there's no need to submit a ticket.

Currency Rates

WHMCS has the ability to sell in multiple currencies and can automatically update exchange rate fluctuations but it doesn't keep an historic rate table. This is a problem since costs listed on invoices should be reported using the exchange rate at the date of the transaction. Let us give you an example.

An invoice with a balance of 100 euro is issued on 1st January when USD/EUR rate is 1.12. The customer records the invoice on 7th April when rate has changed to 1.09. There's a difference of about 3 euro between January and April.

Normally your customers' accountants take care of exchange rate fluctuations but you can make things a lot easier with Billing Extension. The module snapshots currency exchange rates on a daily basis so that you can display the rate in use directly on invoices like follows (top right corner).

In case you want to customize the look of invoices and show prices in other currencies, you can use the following array that is available in both viewinvoice.tpl (HTML version) and invoicepdf.tpl (PDF) files. Below we provide some examples based on a WHMCS that uses USD (default), GBP and AUD currencies.

All amounts of invoice are included in the array to let you display any value in any currency. If the array is empty it means that there are no available exchange rates for the date the invoice has been issued. Now let's move to an example. Here is how we managed to display Total in all currencies on viewinvoice.tpl.

Let's suppose you want to display AUD right next to invoice items. This is a little bit different since you'll need to iterate over the array but it is not that complicated.

As for invoicepdf.tpl, it's all the same. The only difference is that for accessing to $bx_currencies array, you'll need to use PHP syntax instead of Smarty one. For example {$} in PHP becomes $bx_currencies['GBP']['total']. To avoid any possible confusion below we "converted" in PHP the example we just saw for invoice items.


Starting from WHMCS version 7.7 (release date 11th February 2019) there's a new field named Tax ID that is used to contain the client VAT Number. It took more than 10 years to have this field integrated in WHMCS but we decided not to use it for billing purposes for following reasons:

  • Billing Extension already handles Tax ID since 2014
  • The VIES powered by WHMCS has flaws and is not complete
  • From time to time WHMCS takes inexplicable decisions that could break invoicing in case Tax ID is involved
  • The idea of basing things like ABN or electronic invoicing on a field that WHMCS can change without any notice is scary
That being said, for European and Australian companies we'll keep relying on Client Custom Fields when it comes to Tax ID. WHMCS Tax ID will be used only for other countries.

Invoice Suppression

This feature can help reducing the number of invoices, saving your company paperwork, manpower and money. Occasionally WHMCS issues zero balance invoices (no amount). This event occurs also when customers order free services, use 100% discount coupon codes or fully pay invoices with their credit balance. In most of the countries such invoices can be suppressed since there are no payments involved. Before enabling any of these features please consult your accounting advisor.

Apart from reducing the number of unnecessary invoices, starting from version 2.2.56 there's an option, Anti-Fraud, that allows to postpone invoices for new customers. This feature is particularly useful to prevent WHMCS from issuing invoices for fraudolent orders. Such orders in fact give rise to a great number of invoices that need to be registered and reversed by issuing an equivalent number of credit notes. It's a frustrating activity that ruins your billing reports and in the long run could even be considered suspicious by Authorities.

When Anti-Fraud is enabled, new customers (ones with no invoices issued on their accounts) don't receive any invoice even when they send money with real-time payment methods like PayPal or credit card. Billing Extension temporarily moves such payments to Billing page where you can manually issue invoices when you verified that the order was legit. Anti-Fraud doesn't involve existing customers and ones that have been prebviously verified.

Suppression Notification

When an invoice is suppressed, Billing Extension suppresses also the sending of any related email notification to avoid confusion with clients that otherwise would receive emails referred to invoices that no longer exist.

If you still want to send a notification, the module gives you the possibility to choose one from the available Email Templates. You can also create a custom Email Template (category must be General). In both cases in your template you can use the variables described below.

{$suppress_reason} contains the reason why the invoice has been suppressed. At the time of writing, it can assume the following values:

  • FullDiscount when 100% discount is applied on invoice and you choose to suppress it
  • NoAmount when invoice has no amount and you choose to suppress it
  • FullCredit when invoice is fully paid by credit and you choose to suppress it
  • AddFunds when invoice is for adding funds and you choose to suppress it
  • OneInvoice when OneInvoice is in use

The other variable you can use is {$suppress_invoice} that assumes the following values:

  • Skip when depending on your settings the generation of invoice is unnecessary
  • No when the generation of invoice has been delayed to a later stage (e.g. OneInvoice)
Use the provided variables to display custom messages in your emails using simple "if" conditions of Smarty.


It may seem that overpayments happen rarely but in reality they occur pretty much frequently. Sometimes clients forget that they have already paid for their services or that they have an automatic subscription with PayPal. Other times even though they cancelled their services with you they forget to delete existing subscriptions for automatic payments. When such events occur, WHMCS handles them incorrectly.

First the overpayment is registered on the existing invoice. That means that an invoice issued last year moves to current year leading to billing mistakes. This process can repeat itself for every subsequent overpayment.

Secondly WHMCS converts the overpayment into credit balance. The principle is correct but sadly the process doesn't leave any trace and is based on wrong tax calculations. Let's see how this feature of Billing Extension can help you.

Let's assume that there's a proforma of 10 euro. The most common scenario is when the customer pays the proforma that turns into an invoice. Later on a new payment arrives resulting in an overpayment that is registered on a new invoice. This leaves the original invoice unchanged. Below you can see a preview of the newly generated invoice. Notice how inside round brackets there's the reference to the original invoice.

The other possible scenario is that a customer overpays the proforma with the first payment. In this case there's no need to create a new invoice. The module updates the overpaid proforma before it turns into an invoice adding a new line.

It's worth to mention that overpayments can be taxed depending on tax rules. Moreover if you are applying taxes to add funds invoices, Billing Extension also makes sure that the customer receives the correct amount in his credit balance (net of tax).

Tax Displaying

WHMCS shows tax line on invoice only when tax value is greater than zero. In some countries the law requires that tax line is always visible on invoices even when there's no amount. If you are in one of those countries enable this option.

Reference Numbers

For a number of reasons (eg. OneInvoiceBilling Extension could abort the issue of an invoice to issue it at a later stage. When this event occurs, we say that the invoice has been suppressed.

Even though this is a perfectly normal process, customers may find confusing the absence of any reference to the original proforma. That's where Reference Number feature comes to help preserving reference numbers on invoice items as you can see in the example below.

Reference number is available also on standard invoices and credit notes using the following variables:
  • For viewinvoice.tpl {$reference_proformanum}
  • For invoicepdf.tpl $reference_proformanum
This way customers can see reference number directly on invoices. In the example below you can see how it looks on PDF (left) and HTML version of invoice (right).

Notice that reference number shows up only on invoices and credit notes since it would be pointless on proformas. The multi-language message can be customized overriding the following language variable.

$_ADDONLANG['hook']['clientsdetails']['invoice']['referencenum'] = '(Proforma #%proformanum)';

We do understand that editing invoicepdf.tpl is difficult since it uses TCPDF syntax therefore let us show you how you can get the following result.

This is the complete snippet to use right after Invoice Header section.

$pdf->SetFont($pdfFont, 'B', 15);
$pdf->Cell(0, 8, $pagetitle, 0, 0, 'L', '1');
$pdf->SetFont($pdfFont, '', 8);
$pdf->Cell(0, 6, $reference_proformanum, 0, 0, 'R', '1');

Reset Invoice Numbers

Let's face it. Many of us frequently forget to reset invoice number at the beginning of financial year. For many consecutive years WHMCS always tried to help us by releasing small scripts and modules that sadly have worked very rarely. Our feature works without any issue. Not only it resets invoice number but also credit note one when in use. That said, our tool requires that your daily cron runs on daily basis exactly at midnight (00:00 o'clock).

Comments (0)

Speak Your Mind Cancel Reply