WHMCS invoice template customization starts with two files in the active system theme: viewinvoice.tpl for the invoice a client sees on screen and invoicepdf.tpl for the PDF invoice. Change the logo, company details, numbering and tax ID in settings first. For layout changes, copy both files into a child theme, so a WHMCS update does not overwrite your work.
Which files produce the WHMCS invoice and the PDF invoice?
Two files in the folder of the active system theme produce them, with optional header and footer files for the PDF. The Custom PDF Invoices page lists them:
viewinvoice.tplis the invoice a client opens in the browser.invoicepdf.tplis the PDF invoice. It is a PHP template that builds the page with the TCPDF library, so the documentation says you need a basic working knowledge of PHP to edit it.invoicepdfheader.tplandinvoicepdffooter.tplare optional. If they exist in the same directory asinvoicepdf.tpl, WHMCS includes them on every page of the PDF and passes them the same variables.quotepdf.tpl,quotepdfheader.tplandquotepdffooter.tpldo the same for quotes.
This applies to self-hosted installs. The documentation says WHMCS Cloud does not currently support this method.
How do you change the WHMCS invoice logo and company details?
Most of it is a setting, and no template has to change. The logo has two sources. Logo URL, in the General tab at Configuration > System Settings > General Settings, is the image that appears in email messages and on invoices. The PDF is different: its logo is a file named logo.png or logo.jpg in /assets/img/. Both are covered in Customize Your Logo and the PDF page. I point both at the same image.
| What you want to change | Where it is changed | Survives updates? |
|---|---|---|
| Logo in emails and on invoices | Logo URL, General tab of General Settings | Yes, it is a setting |
| Logo on the PDF | logo.png or logo.jpg in /assets/img/ | Yes, but confirm the file is still there afterwards |
| Logo width on the PDF | The logo line near the top of invoicepdf.tpl. Its last number, 75 by default, is the width. | Only if the file is in a child theme |
| Company name | Company Name, General tab | Yes |
| Company address block | Pay To Text, General tab | Yes |
| Your tax or VAT number | Tax/VAT ID Number, General Settings tab of Tax Configuration | Yes |
| A client's tax ID or another client field | Show on Invoice, on the custom field | Yes |
| Paper size and font of the PDF | PDF Paper Size and PDF Font Family, Invoices tab of General Settings | Yes |
Label wording, and the PDF file name ($_LANG['invoicefilename']) | A language override file such as /lang/overrides/english.php | Yes. Files edited directly in /lang are overwritten. |
| Layout of the on-screen invoice | viewinvoice.tpl | Only if the file is in a child theme |
| Layout of the PDF, or a note on every page | invoicepdf.tpl, invoicepdffooter.tpl | Only if the file is in a child theme |
Two font notes from the documentation: Helvetica produces smaller PDF files but suits only standard Latin characters, and Dejavusans supports languages such as Czech, Russian, Arabic and Persian.
How do you customize the WHMCS invoice template so an update does not overwrite it?
Put the files you change in a child theme and leave the parent theme alone. The developer documentation's Child Themes page recommends this for customizing the themes that ship with WHMCS. A child theme is a new folder in /templates with a theme.yaml that names the parent, and any file you add to it overrides the same file in the parent.
- Create the child theme. My WHMCS theme structure guide has the folder layout and the
theme.yamlformat. - Copy
viewinvoice.tplandinvoicepdf.tplfrom the parent, for exampletemplates/twenty-one/, into the child. Edit the copies. - Create
invoicepdffooter.tplorinvoicepdfheader.tplnext to yourinvoicepdf.tplif you want one. - Preview with
?systpl=mythemeon a Client Area URL. Then select the theme under System Theme in the General tab and check the PDF again.
The cost is that a copied file no longer changes when the parent does. After each WHMCS update, compare your copies with the new parent files.
Where are the invoice numbering, proforma and tax ID settings?
They are split between two pages: the Invoices tab at Configuration > System Settings > General Settings, and Configuration > System Settings > Tax Configuration.
| Setting | Where | What it does |
|---|---|---|
| Invoice Starting # | Invoices tab | Sets the number of the next invoice. Enter only a number higher than the latest invoice. The field is empty again after saving, which is normal. |
| Custom Invoice Numbering, Custom Invoice Numbering Format, Next Invoice Number | Tax Configuration, General Settings tab | A format such as INV-{YEAR}-{NUMBER}. The tags are {NUMBER}, {YEAR}, {MONTH} and {DAY}. Invoices that already exist keep their numbers. |
| Enable Proforma Invoicing | Invoices tab | Invoices display Proforma Invoice unless their status is Paid, when they display Invoice. It requires Sequential Paid Invoice Numbering. |
| Sequential Invoice Number Format, Next Paid Invoice Number | Invoices tab, and the VAT Settings tab of Tax Configuration | The separate number an invoice receives when it is paid. Auto Reset Numbering in VAT Settings restarts it never, monthly or annually. |
| Tax/VAT ID Number | Tax Configuration, General Settings tab | Your tax ID, shown under the company address on Client Area and PDF invoices. |
| Store Client Data Snapshot | Invoices tab | Keeps the client's name, address and custom field values as they were when the invoice was created. |
| Enable PDF Invoices | Invoices tab | Attaches the PDF to invoice emails. |
The documented steps for custom numbering and for sequential paid numbering both begin by enabling Tax Support in Tax Configuration.
How do you add custom fields or a footer note to a WHMCS invoice?
For a custom field, tick Show on Invoice on the field at Configuration > System Settings > Custom Fields. Client custom fields then print under the name and address, and product custom fields print in the line item description. With Store Client Data Snapshot on, invoices that already exist do not pick up a new field.
A footer note has three routes, depending on what it says:
- Payment instructions. The Bank Transfer and Mail In Payment gateways display their instructions on invoices. Edit them at Configuration > System Settings > Payment Gateways.
- The same note on every PDF page. Create
invoicepdffooter.tpl. Company registration details and payment terms fit here. - A note on one invoice. Use the Notes tab of that invoice. The PDF template receives it as
$notes.
The documented variables in invoicepdf.tpl include $invoicenum, $datecreated, $duedate, $clientsdetails, $customfields, $invoiceitems, $subtotal, $tax, $total, $companyname and $companyaddress.
How do you test the template with a sample invoice?
Create a draft invoice for a test client and check the on-screen and PDF versions before any customer sees them. I do this on a staging copy.
- In the test client's Summary tab click Create Invoice, or use the + icon and New Invoice. Add line items, one with a long description, and enough rows to reach a second page.
- Click Publish, not Publish & Send Email, so no email goes out.
- Open the invoice in the Client Area as that client and download the PDF. Check the logo, Pay To text, tax ID, custom fields, number and totals in both versions.
- Add a payment and look again. With proforma invoicing on, the title and the number should change.
- Repeat for a client with accented or non-Latin characters in the name, a taxed client and a client in a second currency.
Invoices become immutable once they leave Draft status, so keep test invoices on test clients. Also open an older paid invoice and confirm it still reads correctly.
What can go wrong when you customize WHMCS invoices?
The usual failures are a PDF that will not render and edits that vanish after an update. The first five rows are from the Troubleshooting Invoices page.
| What you see | Cause |
|---|---|
TCPDF ERROR: [Image] Unable to get the size of the image | The server cannot load the logo image by URL with cURL, for example because of a firewall. Fix that, or use a relative path to the image in invoicepdf.tpl. |
Maximum execution time ... exceeded in tcpdf.php | Possibly a high-resolution logo image in the PDF. |
| Letters render as question marks in the PDF | The PDF font does not support those characters. Dejavusans, under PDF Font Family, covers more languages. |
| An invoice shows unexpected client details | Store Client Data Snapshot is on, or the client has a billing contact. |
Duplicate entry '2147483647' for key 'tblinvoices.PRIMARY' | Invoice Starting # was set higher than MySQL can hold. |
| Your layout is gone after an update | The files were edited inside the parent theme. |
- A PHP mistake breaks every PDF. That includes the PDFs attached to invoice emails. Test before you switch themes.
- Numbering is hard to undo. The documentation says to only increase Next Invoice Number, never decrease it. It also notes that some accounting practices, particularly for EU-based companies, require sequential numbers on paid invoices. The rules differ by country, so agree the format with your accountant first.
- Hard-coded text. A currency symbol or address typed into a template is wrong for some clients. My WHMCS multi currency setup guide covers invoices per currency.
Invoice and PDF template changes are part of my WHMCS theme customization work, alongside my other WHMCS services. I start with a free scoping call of about 30 minutes and send a written quote within one business day.
Last reviewed 10 October 2026. Disclosure: I am a freelance WHMCS developer and I sell WHMCS theme and invoice template customization, so I am not neutral. I am CTO at ElySpace, a developer at Marmaids LLC, and founder of WHMCSPilot, which sells WHMCS themes, and MagizAI. File names, settings and error messages are from the WHMCS 9.0 documentation and developers.whmcs.com as I read them on that date.
