Skip to content
Shahid Malla

WHMCS Invoice Template Customization: Files, Logo, PDF, Settings

The WHMCS invoice template checked against the official docs: viewinvoice.tpl and invoicepdf.tpl, the logo, Pay To Text, child themes, numbering, proforma invoices, tax IDs, custom fields and testing.

· Published · Updated · 11 min read · 8 steps

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.

Decision flow for a WHMCS invoice change: a setting first, then a language override for wording, then a child theme footer file, PDF template or on-screen template
Where each kind of invoice change belongs, from a setting down to a template file. Source: shahidmalla.com.

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.tpl is the invoice a client opens in the browser.
  • invoicepdf.tpl is 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.tpl and invoicepdffooter.tpl are optional. If they exist in the same directory as invoicepdf.tpl, WHMCS includes them on every page of the PDF and passes them the same variables.
  • quotepdf.tpl, quotepdfheader.tpl and quotepdffooter.tpl do 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 changeWhere it is changedSurvives updates?
Logo in emails and on invoicesLogo URL, General tab of General SettingsYes, it is a setting
Logo on the PDFlogo.png or logo.jpg in /assets/img/Yes, but confirm the file is still there afterwards
Logo width on the PDFThe 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 nameCompany Name, General tabYes
Company address blockPay To Text, General tabYes
Your tax or VAT numberTax/VAT ID Number, General Settings tab of Tax ConfigurationYes
A client's tax ID or another client fieldShow on Invoice, on the custom fieldYes
Paper size and font of the PDFPDF Paper Size and PDF Font Family, Invoices tab of General SettingsYes
Label wording, and the PDF file name ($_LANG['invoicefilename'])A language override file such as /lang/overrides/english.phpYes. Files edited directly in /lang are overwritten.
Layout of the on-screen invoiceviewinvoice.tplOnly if the file is in a child theme
Layout of the PDF, or a note on every pageinvoicepdf.tpl, invoicepdffooter.tplOnly 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.

  1. Create the child theme. My WHMCS theme structure guide has the folder layout and the theme.yaml format.
  2. Copy viewinvoice.tpl and invoicepdf.tpl from the parent, for example templates/twenty-one/, into the child. Edit the copies.
  3. Create invoicepdffooter.tpl or invoicepdfheader.tpl next to your invoicepdf.tpl if you want one.
  4. Preview with ?systpl=mytheme on 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.

Four steps to an update-safe WHMCS invoice: create a child theme, a folder in /templates with a theme.yaml naming the parent; copy viewinvoice.tpl and invoicepdf.tpl into it and edit the copies; optionally add invoicepdfheader.tpl or invoicepdffooter.tpl; preview with ?systpl=, then select it under System Theme and check the PDF. After each WHMCS update, compare the copies with the new parent files.
The steps above, with the check that copied files need after every update. Source: shahidmalla.com, from the WHMCS developer documentation on child themes.

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.

SettingWhereWhat it does
Invoice Starting #Invoices tabSets 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 NumberTax Configuration, General Settings tabA format such as INV-{YEAR}-{NUMBER}. The tags are {NUMBER}, {YEAR}, {MONTH} and {DAY}. Invoices that already exist keep their numbers.
Enable Proforma InvoicingInvoices tabInvoices 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 NumberInvoices tab, and the VAT Settings tab of Tax ConfigurationThe separate number an invoice receives when it is paid. Auto Reset Numbering in VAT Settings restarts it never, monthly or annually.
Tax/VAT ID NumberTax Configuration, General Settings tabYour tax ID, shown under the company address on Client Area and PDF invoices.
Store Client Data SnapshotInvoices tabKeeps the client's name, address and custom field values as they were when the invoice was created.
Enable PDF InvoicesInvoices tabAttaches the PDF to invoice emails.
Custom Credit Note Numbering, Custom Debit Note NumberingTax Configuration, General Settings tabSeparate 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.

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.

  1. 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.
  2. Click Publish, not Publish & Send Email, so no email goes out.
  3. 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.
  4. Add a payment and look again. With proforma invoicing on, the title and the number should change.
  5. 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 seeCause
TCPDF ERROR: [Image] Unable to get the size of the imageThe 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.phpPossibly a high-resolution logo image in the PDF.
Downloading a PDF invoice logs the client outpdo_mysql clients in the server configuration caused unexpected behavior in PHP.
Letters render as question marks in the PDFThe PDF font does not support those characters. Dejavusans, under PDF Font Family, covers more languages.
An invoice shows unexpected client detailsStore 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 HealthThe setting allows non-Draft invoices to be edited. The Admin Area warns too, until an admin dismisses it.
Your layout is gone after an updateThe 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.

Share this article

Shahid Malla

Written by

Shahid Malla

Freelance WHMCS developer and web designer with 13+ years of client work. CTO at ElySpace, freelance developer for Marmaids LLC, and founder of WHMCSPilot and MagizAI.

Got a project like this?

Tell me what you need and I will send a written quote within one business day.