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.
In words: if WHMCS has a setting for it, change the setting. If only a label's wording is wrong, use a language override file. If the text must repeat on every PDF page, create invoicepdffooter.tpl. Otherwise edit invoicepdf.tpl for the PDF or viewinvoice.tpl for the screen, both in a child theme.
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, and below the documented maximum of 499,999,999. 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. |
| Custom Credit Note Numbering, Custom Debit Note Numbering | Tax Configuration, General Settings tab | Separate formats, next numbers and Auto Reset Numbering for credit and debit notes. Only increase a next number. |
The documented steps for custom numbering and for sequential paid numbering both begin by enabling Tax Support in Tax Configuration.
What do credit notes and invoice immutability change?
They change what you can edit after an invoice leaves Draft. The Credit and Debit Notes page is plain about it: non-Draft invoices are immutable by default, so WHMCS generates a billing note instead of editing one. A credit note reduces an invoice balance. A debit note increases it, a late fee for instance.
- The compliance state is now a setting. Invoice Immutability, on the Invoices tab, has three states: full compliance, immutability disabled with billing notes still generated, and both disabled. The lower two states show an Invoice Immutability warning at Configuration > System Health.
- Clients see the notes. They are listed at Billing > My Credit and Debit Notes.
- No note template is documented. The Custom PDF Invoices page lists invoice and quote templates only. Check what your install produces before promising branded credit notes.
Version matters. On 15 November 2026 the WHMCS documentation version page listed 9.1 as General Availability, released 10 November 2026, and 9.0 as Long-Term Support ending 31 December 2026. Check tab names against your own version.
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.
For sellers in Germany, my German Invoice PDFs addon (I sell it) adds the details § 14 UStG requires, such as the service period under each line and the tax shown per rate.
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.
In the default compliance state, invoices become immutable once they leave Draft, so keep test invoices on test clients. Cancelling a published one creates a credit note rather than removing the invoice. 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. Every row but the last is 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 of 300 seconds exceeded in tcpdf.php | Possibly a high-resolution logo image in the PDF. |
| Downloading a PDF invoice logs the client out | pdo_mysql clients in the server configuration caused unexpected behavior in PHP. |
| 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. |
| An Invoice Immutability warning at Configuration > System Health | The setting allows non-Draft invoices to be edited. The Admin Area warns too, until an admin dismisses it. |
| 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. Where a country also requires the invoice as structured data, my WHMCS e-invoicing guide covers what WHMCS does natively and the routes to add it.
- 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.
What else do people ask about WHMCS invoice templates?
How do I add bank details to a WHMCS invoice?
If clients pay by bank transfer, put the details in the Bank Transfer gateway at Configuration > System Settings > Payment Gateways. WHMCS displays those instructions on invoices. If the details must appear on every PDF page, I put them in invoicepdffooter.tpl in a child theme instead.
Can I customize invoice templates on WHMCS Cloud?
Not with template files. The WHMCS documentation says WHMCS Cloud does not currently support the custom PDF invoice method. It applies to self-hosted installs, where the files are viewinvoice.tpl and invoicepdf.tpl in the active system theme.
How do I change the file name of the WHMCS PDF invoice?
The file name comes from the language string $_LANG['invoicefilename']. Change it in a language override file such as /lang/overrides/english.php. Files edited directly in /lang are overwritten by updates.
Why do some letters show as question marks in a WHMCS PDF invoice?
The PDF font does not support those characters. Set PDF Font Family to Dejavusans on the Invoices tab of General Settings. It supports languages such as Czech, Russian, Arabic and Persian, while Helvetica suits only standard Latin characters.
Why can I no longer edit a WHMCS invoice?
Because non-Draft invoices are immutable by default, and WHMCS records the change as a credit or debit note instead. An admin can change this at Invoice Immutability on the Invoices tab, but the documentation recommends adapting your workflow instead.
Can I change the numbers of invoices that already exist?
No. When you turn on Custom Invoice Numbering, invoices that already exist keep their numbers. The documentation also says to only increase Next Invoice Number, never decrease it. So I agree the format with the accountant before the first live invoice.
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 15 November 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 freelance developer for Marmaids LLC, and founder of WHMCSPilot, which sells WHMCS themes, and MagizAI. File names, settings and error messages are from the WHMCS 9.1 documentation and developers.whmcs.com as I read them on that date.