Customizing WHMCS Proforma Invoice Credit Note Settings

Back   Posted on 1 september 2018 / Updated on 24 january 2021
Reading time 4 minutes

General Settings

Before you start changing settings, it is recommended that you understand the difference between proforma, invoice and credit note. In Billing Extension each type of document comes with dedicated settings.

Visit Addons > Billing Extension > Settings page. The first thing to notice is that proforma and credit notes can be enabled or disabled individually. This is not possible for invoices as they are the minimum requirement to run a business.

Most of the options fall into multiple categories. For example, sequential numbering, number format and increment is available for proforma, invoices and credit notes. In this chapter we're going to focus on them.

Custom Invoice Numbering Format

This is the format of to apply to invoices, proforma and credit notes WHMCS generates. The field can contain any text and number but you can also use auto tags that Billing Extension replaces with their respective values.

Auto Tag Description
{NUMBER} The value for next invoice, proforma or credit note number
{YEAR} Current date in four-digit format
{MONTH} Current month in two-digit format
{DAY} Current day in two-digit format
{ID} System ID of invoice, proforma or credit note
{USERID} Customer ID
{COUNTRY} Customer country in two-letter format (ISO 3166-1 alpha-2)
{CURRENCY} Customer currency in three-letter format (eg. EUR, USD)
{VIITENUMERO} Check digit used for Finnish invoices
{A} Random uppercase letter (A-Z Latin alphabet)
{a} Random lowercase letter (a-z Latin alphabet)
{n} Random number (0-9)
{CN} Special tag that can be used only in specific conditions

Basically it's the same principle we use for the automatic batch invoice PDF export.

If you plan to use {A}, {a} and {n} tags, make sure there are enough combinations. For example with a format like {YEAR}-{n} you can issue a maximum of 10 unique documents. The table below offers more examples.

Number format Example Combinations
{n}{n}{n} 256, 485 729
{A}{A}{A} AHT, PEX 17.576
{n}{n}{n}{n} 84961, 55129 59.049
{n}{n}{n}{n}{n} NW165, TR236 492.804
{A}{A}{A}{n}{n} JER85, SBH77 1.423.656
{A}{A}{A}{A}{A} UYBED, VRWUL 11.881.376

Here are some "standard" examples.

Number format Example
Katamaze{YEAR}-{NUMBER} Katamaze2020-125
{MONTH}/{USERID}-{NUMBER} 12/2-125

There are no limits to customization. You can pick any tag and use it in any order. The same tag can be used multiple times.

Check Digit Viitenumero

{VIITENUMERO} auto tag deserves a more in depth analysis. It's a check digit used by Finnish companies to ensure invoice numbers are correct based on an algorithm:

  • The digits of {NUMBER} are multiplied by 7, 3, 1, 7, 3, 1 etc. from right to left
  • The product of each moltiplication is added up
  • The resulting sum is deducted from the next tenth

Let's see an example with {NUMBER} 3025:

  • 5 x 7 = 35
  • 2 x 3 = 6
  • 0 x 1 = 0
  • 7 x 3 = 21

The total is 62 that needs to be deducted from the tenth therefore we have 70 - 62 = 8. This is the Viitenumber that needs to be placed right after number {NUMBER}{VIITENUMERO} so that it becomes 30258.

In case you need to both numbers separately or to apply customizations, you can use the following variables:

  • {$viitenumero} for viewinvoice.tpl
  • $viitenumero for invoicepdf.tpl

There's also a feature that puts a space every 5 carachers (right to left) and adds leading zero if {NUMBER} is less than 3 digits (eg. 178 96553, 178 96566, 178 96579).

Next Number

Unlike WHMCS, Billing Extension keeps three separate numbering sequences respectively for proforma, invoice and credit note meaning that {NUMBER} auto-tag works like follows:

  • Proforma {NUMBER} 1, 2, 3...
  • Invoice {NUMBER} 1, 2, 3...
  • Credit note {NUMBER} 1, 2, 3...

If desired, you can update Next ID for each document type. For example you can change proforma Next ID to 1000 to start sequential numbering from 1000. Or you can decrease invoice Next ID by 1 in case you deleted an invoice and need to reissue one to avoid leaving a gap.

The possibility to alter next IDs is useful also in case you're starting to use WHMCS in mid year. This way you can continue following your sequential numbering without being forced to start from 1.

Please, be very cautious when changing these values. If this is not done correctly, you could end up with duplicated numbers or gaps in the sequence.

If you're using the feature that sync invoice numbering across multiple WHMCS, changes to Next ID must be replicated on all systems.

Sharing Invoice Numbering Sequence

One can choose to have separate sequential numbering for invoices and credit notes or use the same sequence for both. It's up to you and your country regulations. Let's see a quick comparison.

Separated Shared
Invoice #1 Invoice #1
Invoice #2 Invoice #2
Credit note #1 Credit note #3
Invoice #3 Invoice #4
Credit note #2 Credit note #5

You can change this option from Addons > Billing Extension > Settings > Credit Notes > Dedicated Sequential Numbering.

From time to time you may want to have shared numbers but in the same time define a string to mark credit notes. It could be a prefix, suffix or whatever you want. This is where the special auto-tag {CN} comes to help (requires Billing Extension 2.2.147 or earlier).

This tag is available for invoices therefore it works only inside Addons > Billing Extension > Settings > Invoices > Number Format. It can be used to mark credit notes. It takes two parameters like in the following examples:

  • {CN|anything}
  • {CN|you-want}
  • {CN|including-numbers}
  • {CN|and spaces}

Let us show you how how it works with some examples based on {YEAR}-{NUMBER}{CN|-CN}.

Document Number Format
Invoice #2021-1
Credit note #2021-2-NC
Credit note #2021-3-NC
Invoice #2021-4
Credit note #2021-5-NC

Basically the module looks for {CN} tag then proceed replacing it with the value of second parameter that in our case is "-CN".

Comments (0)

Speak Your Mind Cancel Reply