Skip to main content

Get started with HTML templates

Zuora

Get started with HTML templates

  1. Last updated
  2. Save as PDF

The HTML Templates feature provides key capabilities to design and customize HTML templates online for billing documents, including invoices, credit memos, and debit memos. All public Zuora objects and fields are available for presence on the template, including custom objects and custom fields. 

Zuora provides an online HTML template editor for you to manage HTML templates for billing documents according to business demands.

HTML template editor

In the online HTML template editor, you can switch between the Edit mode and Preview mode.

In Edit mode, you can create and customize HTML templates for billing documents according to business demands.

The online HTML template editor in Edit mode mainly consists of the following tabs to provide customization capabilities:

  • In the Contents tab, you can drag and drop different components from the tab to the editor to define content components included in templates.
  • In the Blocks tab, you can easily define the headers and footers used in the template. You can also use prebuilt design blocks to organize your template content flexibly.
  • In the Body tab, you can configure different settings to customize the default overall template style and appearance, including the text color, background color, content alignment, and font.

In Preview mode, you can select an account and a billing document to preview the rendered PDF file online. For more information, see Preview billing documents in HTML templates.

Search and insert merge fields into a document template

The object schema tool provides a database of field values helpful for customizing your document templates. Your template content can leverage fields to display values from various objects. Your template merge fields are automatically updated to personalize the PDFs of invoices, credit memos, and debit memos that are sent to your customers.

To search for a merge field in an HTML template through the Zuora UI, perform the following steps:

  1. Click your username at the top right and navigate to Billing > Manage Billing Document Configuration.
  2. On the Manage Invoice, Credit/Debit Memo Templates tab, click Add New Html Template.
  3. The Choose a Template from the Library page gets displayed.
  4. Hover over any template for usage in the Invoices, Credit Memo, or Debit Memo tab.
  5. Click the Show Object Schema  icon to do a quick merge field search.
  6. Now, do a quick search based on the considerations listed in Data Schema.
  7. Copy the object or string to include it in the template and click Save.

Considerations

  • The search function activates when you type more than 2 characters. It is recommended to avoid vague searches on the entire dataset in order to prevent performance issues.
  • Upon loading the page, the search bar will be greyed out, indicating it’s not yet available for searching. The initial search process involves a 1 or 2-second completion time. Once completed, it will be searchable, and you can enter your search query.
  • Search supports the ability to search merge field data paths (i.e., Invoice.Invoicedate)

Limitations

Access to search results is available up to the 5th hierarchical level. To avoid app crashes, the display of hierarchical levels is capped at 5. If search results surpass 1000, the app will limit levels to 4 instead of 5.

The search function cannot search for fields with custom objects as the root. However, custom fields created for invoices, credit memos, and debit memos can still be searched.

Comparison and mapping between Word and HTML templates

Compared to Word Mail Merge templates, HTML templates provide a variety of advanced features. HTML templates can coexist with Word Mail Merge templates. You can assign HTML templates to a subset of accounts, and Mail Merge templates to another subset of accounts.

The following table lists the function comparisons between HTML templates and Word Mail Merge templates.

Functionality Word Mail Merge templates HTML templates
Online editor with Drag & Drop and Preview functionality Not supported Supported
Optimized update and test cycle 14 steps 4 steps
Data access to Zuora objects and fields Limitedly supported Fully supported
Custom objects Not supported Supported
Data manipulation including grouping, filtering, sorting, and so on Limited fields Any fields
Localizing fields in types of Number, Date, Currency Limitedly supported Fully supported
Pre-built headers and footers Not supported Supported
Starter template library Limitedly supported, available in the Knowledge Center Supported, available online
Embedded images and external image URLs Not supported Supported
Template management through Setting APIs Limitedly supported Fully supported

For most merge fields available in Word Mail Merge templates, you can find their equivalents in HTML templates.

For more information about the merge field mapping between Word templates and HTML templates for billing documents, see the following articles:

Use cases for custom templates 

Merge fields for custom templates 

See Merge field syntax for HTML templates for more information.

Merge field mapping

See Merge field mapping for billing documents for more information.

For more communication and discussion about this feature in the Zuora Community, see Community resources for HTML templates. 

Restrictions and limitations

The HTML Templates feature has the following restrictions and limitations, specific to one single template:

  • Images
    • Maximum number of uploaded images: 50
    • Maximum size of an image to be uploaded: 200 KB
    • Supported image types: APNG (.apng), AVIF (.avif), GIF (.gif), JPG (.jpg), JPEG (.jpeg), JFIF (.jfif), PJPEG (.pjpeg), PJP (.pjp), PNG (.png), SVG (.svg), and WEBP (.webp)
  • Merge fields
    • When creating an HTML template, you must add at least one merge field before saving the template.
    • When defining merge fields in HTML templates, you must include the root object in merge fields, for example, {{Invoice.Account.Name}} or {{CreditMemo.AppliedAmount}}.
      • Invoice is the root object for invoice templates.
      • CreditMemo is the root object for credit memo templates.
      • DebitMemo is the root object for debit memo templates.
  • Tables
    • Use a smaller font size for the table data (for example, 8px).
    • Reduce the padding for the row cells in the table (for example, 3px).
    • Minimize the number of columns in the table (preferably fewer than 5 columns).
    • Maintain the top and bottom margins as low as possible.
    • Avoid using images in the header or footer to prevent a significant increase in the PDF file size.
  • Functions
    • Maximum number of fields supported by the SortBy function: 3
    • Maximum number of fields supported by the GroupBy function: 6
  • Hyperlinks 
    • For any hyperlinks in HTML templates, the protocol must be HTTPS.
  • Template size
    • Maximum size of an HTML template: 5 MB
      The uploaded images will be encoded and embedded into the HTML template, so they also contribute to the template size.
  • Fonts
    • To make sure uncommon currency symbols displayed on the generated PDF, use the Roboto font from the font family.
  • Data
    • Maximum number of records being processed in total: 1.5 million (the total records to load to generate an invoice, a credit memo, or a debit memo)
    • Maximum number of records that can be processed per object type: 1 million
    • Maximum number of items that can be displayed in a table: 25,000
  • Generated documents
    • If the billing document is using HTML Templates, no MS Word Document is generated even though you enable the Generate MS Word Document permission when setting Billing Roles.