PDF Invoice Customisation

From WHMCS Documentation

Revision as of 16:07, 11 February 2019 by Matt (talk | contribs) (Additional Fonts)

There are 2 invoice templates. One is for the client area invoice (viewinvoice.tpl). The other is for the PDF version of an invoice (invoicepdf.tpl). The templates are found in the active WHMCS template folder.

The logo displayed on the PDF invoices is in the /assets/img/ folder. To change this logo, upload the required logo to the /assets/img/ folder. The name of the file should be "logo.jpg" or "logo.png".

The width of the logo image can be changed in the invoicepdf.tpl template file. On line 10, adjust the last number "75" before the closing bracket );. This variable defines the image width. A developer can then experiment increasing and decreasing it until happy.

Header & Footer

This section describes a feature available in version 7.0 and above

It is possible to have a header and/or footer automatically repeat on every page of a multi-page PDF invoice. The following template files, if present in your theme, will be automatically included for every rendered PDF page:

  • invoicepdfheader.tpl
  • invoicepdffooter.tpl

Only the respective header or footer file is required. For example, if you just want a customized footer on each page, you only need to create invoicepdffooter.tpl. These files must be located in the same directory as the invoicepdf.tpl template file. During template processing, Smarty will provide each of these template files the same variables as invoicepdf.tpl.

Editing Text & Content

A developer can customise the PDF invoices. This includes adding or removing text, altering the layout or adding further images & formatting. Do this by editing the template file invoicepdf.tpl in the active template folder. The file contains all the code relating to the layout and display of the invoice in its PDF format. A basic working knowledge of PHP coding to understand and modify the file.

Displaying Custom Fields

It is possible to display Custom fields on printable and PDF invoices. Do this by ticking the Setup > Custom Client Fields > Show on Invoice option.

The following variables are available for use in the invoicepdf.tpl file. Obtain further data by running SQL queries from within the PHP template.

  • $invoiceid - The ID of the invoice
  • $invoicenum - The custom number of the invoice (only set when proforma or sequential invoicing is enabled)
  • $datecreated - Creation Date of the invoice
  • $duedate - Due date of the invoice
  • $datepaid - Shows paid date/time if invoice status is Paid
  • $userid - Client ID Number
  • $clientsdetails["firstname"] - Client Info First Name
  • $clientsdetails["lastname"] - Client Info Last Name
  • $clientsdetails["companyname"] - Client Info Company Name
  • $clientsdetails["fieldname"] - etc...
  • $clientsdetails["customfields1"] - Client Info Custom Field #1
  • $subtotal
  • $tax
  • $taxrate
  • $credit
  • $total
  • $status - Paid, Unpaid or Cancelled
  • $paymentmethod
  • $notes
  • $companyname - The Company Name
  • $companyurl - The Default Website URL
  • $companyaddress - The Company Address
  • $invoiceitems - Array of invoice items

Changing/Translating Filename

The default filename for invoices is Invoice-xxx. For quotes, this is Quote-xxx. For both, xxx is the ID of the invoice or quote. It may be desirable to change the filenames the clients see or translate into other languages. Achieve this in the same way as any text within WHMCS, by using the Language Files. Look for the strings:

$_LANG['invoicefilename'] = "Invoice-";
$_LANG['quotefilename'] = "Quote-";

Reducing the Filesize of PDFs

The bulk of the file size for PDFs generated by WHMCS come from the embedded font files for UTF-8. Because the UTF-8 charset has a large range of supported characters, this means it takes up more space than say the iso-8859-1 charset. Unlike UTF-8, iso-8859-1, only supports A-Z 0-9 and other standard characters.

If no clients are using special characters in their names/addresses then UTF-8 is not required. It is then possible to reduce the filesize of PDF's by changing the font. To do that, go to Setup > General Settings > Invoices > PDF Font Family. Once there, change the selection from "Freesans" to "Helvetica".

Additional Fonts

The use of certain special characters may not be available in the standard font. So, WHMCS supply an alternative font type that supports Czech, Russian, Arabic & Persian among others.

Version 7.7 and later

No additional files are required:

  1. Navigate to Setup > General Settings > Invoices tab
  2. Select the "Dejavusans" option in the PDF Font Family setting
  3. Click Save Changes

Version 7.6 and earlier

To install:

  1. Download the font files from the URL below.
  2. Upload into the /vendor/tecnickcom/tcpdf/fonts/ folder.
  3. Specify the custom font name dejavusans in Setup > General Settings > Invoices > PDF Font Family.


Accented Characters

Due to a PHP limitation, the translations of the "Paid" and "Unpaid" text on the PDF Invoices may not display upper-case accented characters.

Question Marks

Sometimes, question marks appear in the PDF files in place of non-Latin or accented characters. This can suggest the character is not supported by the font. The first thing to try is setting the font to "Freesans" in Setup > General Settings > Invoicing.

If the problem persists, please download and install "dejavusans" as described above Additional Fonts. This font pack contains more characters than standard ones so stands the best chance of working with these characters.

TCPDF error: Missing or incorrect image file

This means the logo.png or logo.jpg file in your /assets/img/ folder is missing or is not a valid image file. This is the image used when creating the pdf invoice. Please re-save the image file and re-upload to the /assets/img directory.