Skip to main content

Creating a Custom Invoice Template


Creating a Custom Invoice Template

With Zuora Billing, you can easily create and manage your invoice templates. Invoice templates are used to generate PDF invoices for your bills.

You can customize your invoice templates to have your company's look and feel (including adding your company's logo). You can also use merge fields to display only the billing and payments information you want your customers to see.

The design for the Invoice Template is focused on flexibility and ease of use for the business user. The Mail Merge functionality provides a great framework to make changes to the look and feel of the invoice template.

Note that invoice templates are set at the customer level, not at the product level.

Sample Invoice Template

Download the sample invoice template, which you can customize using the instructions in this section.

Custom Invoice Template Workflow

Use these instructions with the sample template to start creating your own invoice template.

First, create mail merge fields and use tables to add information to the default template and customize how the invoice displays the information. 

You can then use the advanced mail merge functionality to further customize your invoice template:

Using Your Invoice Template to Create an Account Statement

You can set up your invoice template to include account balance information that is useful for creating statements. There are two fields that can be used to configure your invoices to show full statement information, including the previous account balance, and new balance based on the application of charges on the invoice. These fields are:

  • Account Previous Balance: This is a dynamically calculated field that represents the account balance before an invoice is posted. For example, if an account had one previous invoice with an outstanding balance of $100, and generates a new invoice for $75 showing the Account Previous Balance, this field would show $100 when displayed on the new invoice.
  • Account New Balance: This field represents the balance on an account after the invoice has been posted. In the previous example, the Account Previous Balance was $100, the invoice balance of the invoice is $75, so Account New Balance = $100 + $75 = $175.

Uploading an Invoice Template

Once you have created an invoice template, you can upload it to Zuora.

  1. Click your username at the top right and navigate to Billing > Manage Billing Document Configuration.
  2. In the Manage Invoice Rules and Templates tab, click Add new template.
  3. Enter a Name for the new template.
  4. Click Browse to browse for your template file.
  5. Optionally, select Do not display zero value invoice line items.
  6. Click save.

If you have the Invoice Settlement feature enabled, see Upload Billing Document Templates for steps on how to upload invoice templates.

System Default Template

Click your username at the top right and navigate to Billing > Manage Billing Document Configuration, and you can see a special template called System Default Template in the Manage Invoice Rules and Templates tab. It can be renamed, but unlike other templates it cannot be deleted.

The template file and settings for System Default Template depend on whether or not you have uploaded any custom invoice templates.

If you have not uploaded any custom invoice templates, your System Default Template is set as the standard Zuora template file that is available to download on the Manage Invoice Rules and Templates page. Whether the template setting Uses New Invoice File Generation Service is enabled or not depends on the date you joined Zuora as a customer.


Relationship with the Default Custom Invoice Template

If you have uploaded a custom invoice template and set it as the default template (by clicking the make default link), the System Default Template will be linked to this template. The words [copied from <template name>] will be displayed.

The System Default Template will have the same file as the default template, and also have the same settings for Uses New Invoice File Generation Service and Do not display zero value invoice line items.


Switching the Default Custom Invoice Template

You can make another uploaded template the default template by clicking the make default link next to it. This copies the new default template file and settings to the System Default Template, overwriting its existing contents.


Editing the System Default Template or Copied Default Template

Clicking make default on an uploaded template does two things:

  1. It copies the template file and all settings from the uploaded template into the System Default Template.
  2. It creates a relationship between an uploaded template and the System Default Template.

For as long as the System Default Template and the copied default custom invoice template remain unchanged, the relationship is preserved. The message [copied from <template name>] is displayed next to the System Default Template, to indicate that the two templates are the same.

If you click Edit on either template and change any of the following settings, the relationship is broken. 

  • Replace the template file
  • Change the invoice file generation service
  • Change the rule Do not display zero value invoice line items

These actions cause the message to no longer be displayed, to indicate there may be a difference in the results of invoice generation between the two templates. Renaming either template does not affect the relationship between templates.


How to Ensure a Customer Always Uses the Default Template

The invoice template that is used for a particular customer is defined in that customer's profile. If you set a customer's profile to use the System Default Template, you can ensure that invoices sent to that customer will always use whichever default template is linked to the System Default Template. This allows you to easily change the default template without having to update all your customers' profiles each time.

Setting a Customer's Invoice Template in the Zuora Application

See Creating a Customer Account for instructions on changing a customer's invoice template. To ensure the customer always uses the default template, select System Default Template in the invoice template drop-down.


Setting a Customer's Invoice Template in the API

The System Default Template has its own unique ID value which never changes. The invoice template that is used for a particular customer is defined in the Account.InvoiceTemplateId field. If you set Account.InvoiceTemplateId to the ID of the System Default Template, you can ensure that invoices sent to that customer will always use the default template that System Default Template is linked to.

To find the ID of the System Default, click your username at the top right and navigate to Billing > Manage Billing Document Configuration. On the Manage Invoice Rules and Templates tab, click Show ID next to the System Default Template. The ID is a long hexadecimal number, e.g., 1028e262478a476401478a5034110c2b.


You can set Account.​InvoiceTemplateId with a SOAP API update() call. In the below example, Id is the customer account ID, and InvoiceTemplateId is the ID of the System Default Template.

<ns1:update xmlns:ns1="">
  <ns1:zObjects xsi:type="ns2:Account" xmlns:ns2="" xmlns:xsi="">


If you encounter any problems, see Troubleshooting Custom Invoice Templates for a list of common problems and solutions. 

Avoid Using Complex Invoice Templates

Avoid using complex invoice templates to speed up the invoice PDF generation. See Avoid Complex Invoice Templates for more information.

Supported Merge Fields

See the list of supported merge fields for information about the fields that you can include in your invoice templates.