Historical Currency Rates for Invoice Snapshot in WHMCS
As discussed in difference invoice and credit note, both types of documents have fiscal value hence it is important that invoice details (eg. client's name, address etc.) remain the same. They need to be fixed to that in use at the time they were issued.
As you probably know, WHMCS integrates a feature named Store Client Data Snapshot. As the name suggest, it records invoice data at the time an invoice is generated.
Unfortunately this feature has many drawbacks that we managed to address with invoice snapshots. Unlike Billing Extension, WHMCS doesn't keep track of company details and VIES. Most importantly, it doesn't keep track of exchange rates.
Keeping historical exchange rate data on a system that uses multiple currencies is essential. Accountants need to record gains from foreing exchange rates using the rate in effect on the date on which the invoice is issued.
It might not seem like much, but this is a serious issue. Let us show you a practical example. For simplicity reasons we assume that we're earning 5.000 USD per month.
|EUR / USD rate
|5.000 USD / monthly
At the end of the year we earned 50.000 USD equivalent to 44.245 EUR. This is the effective amount we earned.
Now let's see what happens if we ignore daily currency fluctuations and just stick to one rate backward. Let's use the rate of October 2020. The new amount is now 42.546 €. There's a difference of 1.699 €, almost 4% less.
This example clearly shows why storing historical currency rates in WHMCS is important. Not only it eases the job of your accountant but also lowers the risks of billing mistakes.
First off, Billing Extension keeps track of exchange rates on a daily basis. Please be aware that the module can't retroactively store rates. It starts recording them from the moment you install it on your system.
As for the integration, Billing Extension adds $bx_currencies array to the following invoice files:
- viewinvoice.tpl - printable version
- invoicepdf.tpl - downloadable PDF
Here's a representation of the array in question on a system that uses 4 currencies: EUR (default) USD, GBP and AUD.
As you can see the array provides not only exchange rates but also the actual conversion rate for every amount of the invoice you are currently seeing or downloading.
The screenshot below shows how we implemented it on invoice PDF file. At the top right corner we included the actual EUR/USD currency rate in use at the time the invoice has been issued. We simply placed $bx_currency['rate_tosuffixed'] variable in that corner.
As we show in the following example, you can also get a bit creative. Right below the amount of every invoice item we're showing the correspondent GBP value.
Now let's move to the printable version. The principle is the same. Here we decided to show both GBP and AUD. The only difference is that instead of PHP variables you need to use Smarty ones. The syntax is just a little different.