Skip to main content

Billing: Custom Invoice

Zuora

Billing: Custom Invoice

The custom invoice task generates an invoice PDF file based on the HTML template that you enter in the task, and then attaches the generated PDF file to the invoice that is Draft or Posted status. You can customize your invoice template using HTML tags, CSS, images, JavaScript and Liquid expressions.

For HTML rendering and PDF generation, the task uses the same set of components, including browser engine and PDF engine, as in Chrome version 77.

To test the output of your template, save your template as an HTML file and open it in Chrome (version 77.0.x or later). You can then select Print and use Save as PDF as the destination. The maximum size of a PDF file to upload is 4 MB. If the size of the saved PDF is greater than 4 MB, you need to downsize your template accordingly.

For attaching PDFs to invoices, the task uses the Zuora API that uploads files for invoices. For each invoice, a maximum of 50 PDF files can be uploaded. For details about the API operation, see Upload File For Invoice in the API Reference.

For a complete use case and template code examples, see the "Custom Invoice" workflow template under the Invoicing category. This template is explained in Customize invoice templates using HTML.

Task settings

You need to select or specify a field to identify the invoice and enter the complete template code. Ensure you retrieve invoice IDs in upstream tasks.

workflow_task_custom_invoice.png

Design your template

Use JavaScript or Liquid to add logic or data to the template. You can also reference external JavaScript libraries.

Liquid expressions start with '{%' and end with '%}'.

This code block uses Liquid to pass data to a JavaScript constant object.

const usages =  {% if Data.Usage %}
    {{- Data.Usage | to_json -}};
{%- else -%}
    [{"UOM":"kWh","Quantity":1229.9,"StartDateTime":"2018-08-01T00:00:00.000-07:00"},
    {"UOM":"kWh","Quantity":1265.56,"StartDateTime":"2019-07-01T00:00:00.000-07:00"}];
{%- endif -%}

The following code block adds data to a div element. Depending on the value of a data field, it adds different strings to the div element.

 <div style='font-size: 10px'>
{%- if Data.Invoice[0].InvoiceNumber and Data.Invoice[0].InvoiceNumber != "" -%} 
{{- Data.Invoice[0].InvoiceNumber }}
{%- else -%}0001{%- endif -%}
</div>

To include an image in your template, use the img HTML tag and specify a URL or a Base64-encoded string as the value for the src attribute.

For example, you can include a Zuora logo image using either of the following two HTML snippets.

<img src="https://www.zuora.com/wp-content/themes/zuora/img/zuora-logo.svg">
<img alt="" src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4NCjwhLS0gR2VuZXJhdG9yOiBBZG9iZSBJbGx1c3RyYXRvciAxOC4wLjAsIFNWRyBFeHBvcnQgUGx1Zy1JbiAuIFNWRyBWZXJzaW9uOiA2LjAwIEJ1aWxkIDApICAtLT4NCjwhRE9DVFlQRSBzdmcgUFVCTElDICItLy9XM0MvL0RURCBTVkcgMS4xLy9FTiIgImh0dHA6Ly93d3cudzMub3JnL0dyYXBoaWNzL1NWRy8xLjEvRFREL3N2ZzExLmR0ZCI+DQo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4Ig0KCSB2aWV3Qm94PSIwIDAgMzc4LjMgODIuMyIgZW5hYmxlLWJhY2tncm91bmQ9Im5ldyAwIDAgMzc4LjMgODIuMyIgeG1sOnNwYWNlPSJwcmVzZXJ2ZSI+DQo8Zz4NCgk8cGF0aCBmaWxsPSIjMzg0QjVEIiBkPSJNMjAzLjksODIuMmMtMjIuNywwLTQxLjEtMTguNC00MS4xLTQxLjFTMTgxLjIsMCwyMDMuOSwwczQxLjEsMTguNCw0MS4xLDQxLjFTMjI2LjUsODIuMiwyMDMuOSw4Mi4yeg0KCQkgTTIwMy45LDE4LjJjLTEyLjYsMC0yMi45LDEwLjMtMjIuOSwyMi45UzE5MS4yLDY0LDIwMy45LDY0YzEyLjYsMCwyMi45LTEwLjMsMjIuOS0yMi45UzIxNi41LDE4LjIsMjAzLjksMTguMnoiLz4NCjwvZz4NCjxwYXRoIGZpbGw9IiMzODRCNUQiIGQ9Ik04Ni45LDAuMWgxMi40YzEuNywwLDMsMS4zLDMsM3Y0My42YzAsMTAsMi42LDE3LjIsMTIuNywxNy4yYzE0LjgsMCwyMi4yLTguMywyMi4yLTI4LjFWMy4xDQoJYzAtMS43LDEuMy0zLDMtM2gxMi4zYzEuNywwLDMsMS4zLDMsM3Y3Ni4xYzAsMS43LTEuMywzLTMsM2gtMTIuM2MtMS43LDAtMy0xLjMtMy0zdi03LjdjLTQsOC41LTEzLjcsMTAuNi0yNy43LDEwLjYNCgljLTE3LjYsMC0yNS43LTguOS0yNS43LTMxLjJWMy4xQzgzLjksMS41LDg1LjIsMC4xLDg2LjksMC4xeiIvPg0KPGc+DQoJPHBhdGggZmlsbD0iIzM4NEI1RCIgZD0iTTI1NC40LDAuMWgxMi4zYzEuNywwLDMsMS4zLDMsM3Y3LjdjMCwwLDIuNS0xMC40LDI1LjEtMTAuN2MwLjEsMCwwLjMsMCwwLjQsMGMxLjgsMCwzLjMsMS41LDMsMy4zDQoJCWwtMS42LDEyLjljMCwxLjctMS40LDMtMywyLjljLTAuNiwwLTEuMiwwLTEuOCwwYy04LjcsMC0xNi41LDUuOC0yMC40LDE4Yy0xLjMsNC0xLjgsOC41LTEuOCwxMy40djI4LjdjMCwxLjctMS4zLDMtMywzaC0xMi4zDQoJCWMtMS43LDAtMy0xLjMtMy0zVjMuMUMyNTEuNCwxLjUsMjUyLjcsMC4xLDI1NC40LDAuMXoiLz4NCjwvZz4NCjxwYXRoIGZpbGw9IiMzODRCNUQiIGQ9Ik0zNzguMiwzOS43Yy0wLjQtMTAuMi00LjItMTkuMS0xMS4zLTI2LjZjLTEzLjUtMTQuNC0zNC44LTE2LjctNTAuOC03LjRjLTE0LjYsOC41LTIzLjMsMjUuNS0xOS44LDQzLjcNCgljMywxNS40LDE0LjgsMjguMywzMC43LDMyLjJjMCwwLDAsMCwwLDBjMjUuNiw0LDMzLjItMTAuMiwzMi43LTEwYzAuMi0wLjEsMC4xLDcuNiwwLjEsNy42YzAsMS43LDEuNywzLDMuNCwzaDExLjljMS43LDAsMy0xLjQsMy0zDQoJTDM3OC4yLDM5LjdDMzc4LjMsMzkuNywzNzguMiwzOS43LDM3OC4yLDM5Ljd6IE0zMTQuMSw0MS4zYzAuMS0xMi42LDEwLjUtMjIuNywyMy4yLTIyLjdjMTIuMywwLjEsMjIuNSwxMC40LDIyLjQsMjIuOQ0KCWMwLjEsMTIuOS0xMC45LDIyLjQtMjMuMSwyMi4yQzMyNC4yLDYzLjUsMzE0LDUzLjgsMzE0LjEsNDEuM3oiLz4NCjxwYXRoIGZpbGw9IiMzODRCNUQiIGQ9Ik04NS43LDgwLjJDODUuNyw4MC4yLDg1LjcsODAuMiw4NS43LDgwLjJDODUuNyw4MC4yLDg1LjcsODAuMiw4NS43LDgwLjJDODEuNSw3Nyw4MCw3MS40LDc4LDY0LjcNCgljLTAuMS0wLjUtMC42LTAuOC0xLjEtMC44TDM0LjcsNjRjLTEsMC0xLjUtMS4xLTAuOS0xLjlMNzYuNiwxMmMwLjItMC4yLDAuMy0wLjUsMC40LTAuOFYzYzAtMC4yLDAtMC40LDAtMC42YzAtMC4yLDAtMC40LTAuMS0wLjUNCgljLTAuNC0xLjEtMS41LTEuOC00LjEtMS44SDQuNmMtMi4xLDAtMy44LDEuNy0zLjgsMy44djEwLjljMCwyLjEsMS43LDMuOCwzLjgsMy44aDE4Ljl2MGgyMC42YzEsMCwxLjUsMS4xLDAuOSwxLjlMNi40LDY1LjcNCgljLTMuNSw0LTcuMSw3LjktNi4yLDEyLjJjMC4yLDEuMywwLjgsMi41LDEuNiwzLjVjMC41LDAuNiwxLjIsMC45LDEuOSwwLjlsODEuMywwQzg2LDgyLjIsODYuNSw4MC45LDg1LjcsODAuMnoiLz4NCjwvc3ZnPg0K" /> 

View the output

If the task runs successfully, you can view the output in the Tasks tab. Click the menu icon on the left of the task and hover on Files. You can select either the HTML or PDF version of the invoice. The PDF file is generated based on the HTML file. If you want to do one-time changes, you can modify the HTML file and then generate a PDF file based on the HTML file. 

workflow_custom_invoice_output.png

You can also view the PDF in Zuora UI. It is shown in the History section of the specific invoice.