Skip to main content

Use custom objects in HTML invoice templates

Zuora

Use custom objects in HTML invoice templates

You can use custom objects and fields in HTML invoice templates to display more complex or advanced data in invoices.

Display messages based on locales

You can store translation messages in custom objects including locales and message keys as filterable fields. Later, you can query the translation messages based on message keys and locales, and use them as field labels, table header names, or texts in the template.

To display messages based on locales, perform the following steps:

  1. Define a custom object named messages to store the messages.
    The following table lists the structures of the custom object. For example, KEY is the field label, and key__c is its API name. The fields key__c and locale__c are filterable.

    ID KEY(key__c) LOCALE(locale__c) VALUE(value__c)
    0f9e8dc6-4256-4185-805a-efbb761245a4 invoice_date en_US Invoice Date
    0f9e8dc6-4256-4185-805a-efbb761245a5 payment_terms en_US Payment Terms
    0f9e8dc6-4256-4185-805a-efbb761245a9 invoice_date zh_CN 账单日
    0f9e8dc6-4256-4185-805a-efbb76124510 payment_terms zh_CN 账期
  2. Use filter functions to query the message value based on keys. 

{{#default__messageses|FilterByValue(locale__c,EQ,zh_CN)|FilterByValue(key__c,EQ,invoice_date)}}{{value__c}}:{{/default__messageses|FilterByValue(locale__c,EQ,zh_CN)|FilterByValue(key__c,EQ,invoice_date)}}

Display a list of custom object records

To display a list of custom object records in invoices, perform the following steps:

  1. Define a custom object named reefer to store the reefers that each subscription has.
    One subscription can have multiple reefers. The following table lists the structures of the custom object. The custom object uses Subscription Name as the key, and its API name is SubscriptionName__c.

    ID Brand Number Volumn StartDate Subscription Name
    0f9e8dc6-4256-4185-805a-efbb761245a4 Brand1 10003 50m~3 2021-04-01 A-S00000056
    0f9e8dc6-4256-4185-805a-efbb761245a5 Brand2 10002 100m~3 2021-01-01 A-S00000054
    0f9e8dc6-4256-4185-805a-efbb761245a9 Brand3 10001 100m~3 2021-01-01 A-S00000056
  2. Use the HTML component to configure how to display the reefers that an invoice contains. See Configure HTML codes in HTML invoice templates for more information about the configuration procedure.

    • Use {{#InvoiceItems|Map(Subscription)|Uniq}} to construct the subscription list that the invoice contains.
    • For each subscription, filter reefers based on the subscription number: {{#default__reefers|FilterByRef(SubscriptionName__c,EQ,SubscriptionNumber)}}
    • For each reefer record, display its fields as a row in the table.

    The following information is an example of HTML codes. The style part is ignored.

    <style>
        ...
    </style>
    {{#Invoice}}
    <table class="table-grid u_content_custom_generic_table_2">
    <thead><tr>
         <th style="width:auto; ">
             Subscription Name
         </th>
         <th style="width:auto; ">
             Brand
         </th>
         <th style="width:auto; ">
             Number
         </th>
         <th style="width:auto; text-align:right;">
             Volume
         </th>
         <th style="width:auto; text-align:right;">
             Start Date
         </th></tr></thead>
    <tbody>
    {{#InvoiceItems|Map(Subscription)|Uniq}}
       {{Cmd_Assign(SubscriptionNumber,Name)}}
    
    
       {{#default__reefers|FilterByRef(SubscriptionName__c,EQ,SubscriptionNumber)}}
       <tr>
         <td style="">{{SubscriptionName__c}}</td>
         <td style="">{{Brand__c}}</td>
         <td style="">{{Number__c}}</td>
         <td style="">{{Volume__c}}</td>
         <td style="">{{StartDate__c}}</td>
       </tr>
       {{/default__reefers|FilterByRef(SubscriptionName__c,EQ,SubscriptionNumber)}}
    {{/InvoiceItems|Map(Subscription)|Uniq}}
    
    
       </tbody>
    </table>
    {{/Invoice}}
    

The following image shows the preview result.

Display exchange rates on invoices

Assume that your customers have AED as the home currency, but are billed in USD. You want to present the charge amount and tax in AED on the invoice. The exchange rate that is used to convert from USD to AED is also displayed.

To display exchange rates on invoices, perform the following steps:

  1. Define a custom object named ExchangeRate to store the exchange rate.
    The following table lists the structures of the custom object. The From__c and To__c fields are filterable.

ID

From (From__c)

To (To__c)

Rate(Rate__c)

0f9e8dc6-4256-4185-805a-efbb761245a4

USD

AED

8.00

0f9e8dc6-4256-4185-805a-efbb761245a5

USD

GBP

0.73

0f9e8dc6-4256-4185-805a-efbb761245a9

CAD

GBP

1.09

  1. Use filter functions to query the exchange rate based on home currency (AED) and billed currency (USD).
    You can use the Cmd_Assign command to define a global variable named TheRate, which can be used anywhere in the template.

{{#default__exchangerates|FilterByRef(From__c,EQ,Invoice.Account.Currency)|FilterByValue(To__c,EQ,AED)|First(1)}}

{{Cmd_Assign(TheRate,Rate__c,True)}}

{{/default__exchangerates|FilterByRef(From__c,EQ,Invoice.Account.Currency)|FilterByValue(To__c,EQ,AED)|First(1)}}

  1. Use the TheRate global variable to calculate all amount fields in home currency. 
    The following example is to calculate the total tax amount in home currency.
    {{Account.Currency|Symbol}}{{Invoice.TaxAmount}} ( {{#Wp_Eval}} {{Invoice.TaxAmount}} * {{TheRate}} {{/Wp_Eval}} AED)
    The output is displayed as $1.18 ( 9.44 AE).
    The following example HTML codes are to show an invoice item as a row in a charge details table.

    <tr>
    <td style="">{{ChargeName}}
    </td>
    <td style="">{{ServiceStartDate|Localise}} - {{ServiceEndDate|Localise}}
    </td>
    <td style="text-align:right;">{{Account.Currency|Symbol}}{{ChargeAmount}} ({{#Wp_Eval}}{{ChargeAmount}}*{{TheRate}}{{/Wp_Eval}} AED
    </td>
    <td style="text-align:right;">{{Account.Currency|Symbol}}{{TaxAmount}} ({{#Wp_Eval}}{{TaxAmount}}*{{TheRate}}{{/Wp_Eval}} AED)
    </td>
    <td style="text-align:right;">{{Account.Currency|Symbol}}{{#Wp_Eval}}{{ChargeAmount}}+{{TaxAmount}}|Round(2)|Localise{{/Wp_Eval}} ({{#Wp_Eval}}({{ChargeAmount}}+{{TaxAmount}})*{{TheRate}}|Round(2)|Localise{{/Wp_Eval}} AED)
    </td>
    </tr>
    
  2. Preview the template after you add the merge fields. 

The following image shows an example of the preview result.