Skip to main content

Upgrade to New Invoice File Generation Service


Upgrade to New Invoice File Generation Service

Do I Need to Upgrade?

Zuora recommends that you upgrade your templates to the new invoice file generation service soon so you can benefit from new invoice features as we release them. We will eventually deprecate the old service.

Use the following table to determine if you need to upgrade. It is based on when you first became a Zuora customer.

Initial Zuora Version  Upgrade? Next Steps

 R177 and later
(after June 18th 2014)

Upgrade is not required.

The new invoice file generation service is automatically enabled for any custom invoice templates.

Customize Invoice Templates Using Word Mail Merge

R176 and earlier
(before June 18th 2014)

Upgrade is required.

You are currently using the old invoice file generation service for any custom invoice templates.

Follow the upgrade instructions in this article

Why Upgrade to the New Invoice File Generation Service?

Zuora new invoice file generation service provides you more flexibility in your invoice presentment:

  • Conditional display. You can use IF fields on templates to conditionally display content on the invoice.
  • Table nesting in the usage and invoice items tables.
  • Invoice localization. You can deliver invoices in your customers' preferred languages.
  • Barcode. You can use the BarCode merge field to show a barcode on your invoice.
  • Additional merge fields available for Account, Invoice Item, Invoice, and other critical billing-related objects.
  • Future invoice enhancements will be supported only by the new PDF file generation service.

How Do I Upgrade to the New Invoice File Generation Service?

You must upgrade each of your custom invoice templates according to the following steps:

  1. Test the template for errors
  2. Generate a preview invoice
  3. Compare the old and new PDF invoices
  4. Upgrade the invoice file generation service for the template
  5. Test the template in a bill run

Repeat this process for each of your templates, so that they all use the new invoice file generation service.

Test The Template for Compatibility

Before upgrading a template, you must test it for compatibility with the new service.  Zuora has provided a tool that checks your existing templates for compatibility:

  1. Click your username at the top right and navigate to  Billing > Manage Billing Document Configuration > Prepare Templates for New Invoice File Generation Service.
    Invoice Template 1.jpg
  2. Click Choose File to select a custom template file (Microsoft Word format, .doc extension).
  3. Click upload to upload your template to this page to check for errors generated by the new invoice file generation service.
    Invoice Template
  4. Fix the causes of any errors (mandatory) and any warnings (optional), by following the instructions provided. Then upload the corrected template to verify your changes.
    • Errors: These are issues with your template that must be fixed in order for it to be used with the new invoice file generation service, e.g., the template contains mergefields in an incorrect format.
    • Warnings: These are issues that do not prevent the template from being used with the new invoice file generation service, but may affect the look and feel of the generated invoice, e.g., there are some hidden mergefields in the template.

When no errors are generated by the template upload, the file name will appear in blue text under the Choose File button.
Invoice Template 3.jpg

Generate a Preview Invoice

To ensure that your customer invoices look correct, you need to generate some invoices with the new service and inspect them for issues:

Zuora recommends that you use real customer data if available. If you do not have any existing customers or previously generated invoices, select Use Sample Data.

  1. Select Use Customer Data and click go.  A list of your customers appears. Alternately, enter a customer name to view a specific customer.
  2. Select the customer.
  3. Select an invoice from the drop-down. Only the 10 most recent invoice are returned. 
  4. Click preview invoice to generate a PDF invoice using the selected data and the new invoice file generation  service. The PDF file should begin automatically downloading.
    Invoice Template 4.jpg

Compare Old and New PDF Invoices

It is important to ensure that invoices generated with the new service are no different to those generated with the old service.To do this, you can compare PDF invoices generated using the same data. Mainly, check that the visual presentation of the invoice did not change.  

  1. Locate the PDF invoice that was generated with the old service. Go to Billing > Invoices and search by invoice number, e.g., INV00000484.
  2. Click the invoice name to enter the invoice detail view, and click the View > Invoice PDF to download the invoice file.
    Invoice Template 5.jpg
  3. Open both PDF invoices and compare side-by-side to check for any differences.
  4. If the invoice does render as expected, edit your custom template file.
  5. Repeat the preview process to verify your changes. Once you are happy with the invoice preview, you are ready to upgrade the service the template uses.

Upgrade the Invoice File Generation Service for the Template

  1. Click your username at the top right and navigate to  Billing > Manage Billing Document Configuration > Manage Invoice Rules and Templates tab.
  2. Locate the existing template to upgrade in the list. Click edit.
    Invoice Template 6.jpg
  3. Click Choose File and select the template file that you just tested for compatibility in the previous steps. This file will replace the existing file currently being used to generate invoices.
    Invoice Template 7.jpg
  4. Select New Invoice service.
  5. Click save to start using the new template file with the new invoice file generation service.
  6. Check there is a green tick icon in the Use New Invoice File Generation Service column. This confirms that the new invoice file generation service is being used by this template.
    Invoice Template 8.jpg

Test the Template in a Bill Run

Once the template is upgraded it is important to run a test bill run with many invoices and carefully check the results.

  1. Create an ad hoc bill run, ensuring that auto-post is off for the included customers. For more information, see Creating Bill Runs.
  2. Inspect the generated invoices. If you notice any issues, edit your template and re-upload. You may wish to revert to your old template to allow time to make the template modifications. If so, re-upload the old template and select Existing Invoice service to be able to generate invoices with the old invoice file generation service again.