Merge field syntax

Describes the merge field syntax you can use to include related object data in email or callout templates.

Overview

A merge field serves as a placeholder in email and callout templates to automatically incorporate values from objects when an email or a callout notification is triggered. Merge fields are enclosed by angle brackets or double curly brackets, which depend on the merge field type.

Email and callout templates support all merge field syntax for HTML templates. For more information, see Merge field syntax for HTML templates.

The following table describes the main differences between merge fields in email and callout templates, and HTML templates:

Supported merge field types

Email and callout templates support the following merge field types:

• Advanced merge field
• Data source merge field
• System merge field

Merge field syntax for fields from the base object or joined objects

Most standard or custom events are defined on base objects.

The following table lists the base object for some commonly used events:

When creating or editing an email or a callout template, you can use fields not only from the base object but also from joined objects. For example, if the base object is Invoice, you can use fields from Invoice and fields from Account, Bill To, Send To, and Default Payment Method objects.

The following table lists merge field syntax for each object field:

Note that advanced merge fields must start with the base object related to the event.

For example, if you would like to retrieve a product name from an OrderAction event, you should access the Product object in the following order:

OrderAction → Subscription → RatePlan → Product

For more information on extended objects, see Zuora business object model.

If you receive the following error message when creating email templates:

“Email body rendering error: X can not be used as root level mergCe field in a template”

It indicates that there was an issue with getting the right object and field in the notification because of incorrect merge field syntax.

As shown in the following table, if the merge field is for email or callout templates related to the Invoice Due event, the first object must be Invoice instead of Account:

You can use the following merge field syntax if the base object is a custom object:

Merge field syntax for custom fields from custom objects

When using custom fields from custom objects as merge fields in email or callout templates, you must follow these rules:

• Use section and variable merge fields (start with {{#...}} and end with {{/...}}).
• Add the default__ prefix to custom object names.
• Use custom object names in their plural form.

For more information and examples about merge field syntax for custom objects, see Use custom objects in HTML templates.

There are two main scenarios for using custom object fields as merge fields in email or callout templates:

Merge field resolving

When an event is triggered, a specific object record of the base object type is considered as the context data. Zuora replaces all merge fields in email or callout templates with the corresponding values from the context data or other related objects before sending notifications.

The following table provides details on the base object and context data for some commonly used events:

For example, suppose that the context data (an invoice) of a triggered Invoice Due event is as follows:

{
    "id": "8ad0962d87bc17870187c0ff4dc80cca",
    "invoiceNumber": "INV00065283",
    "accountId": "2c92c0f959916d780159973781be2f15",
    "amount": 150.000000000,
    …
}

The account info of this invoice is as follows:

{
    "basicInfo": {
        "id": "2c92c0f959916d780159973781be2f15",
        "accountNumber": "A00000077",
        "status": "Active",
        …
    },
    …
}

The custom object records linked to the Invoice object are as follows:

{
    "Id": "14b65982-a61f-4452-b89d-59b072506a08",
    "type": "MyObject",
    "invoiceID__c": "8ad0962d87bc17870187c0ff4dc80cca",
    "mydata__c": "My Data 1",
    …
},
{
    "Id": "66e1a250-c544-4cc9-8ebc-72dcce36c40c",
    "type": "MyObject",
    "invoiceID__c": "8ad0962d87bc17870187c0ff4dc80cca",
    "mydata__c": "My Data 2",
    …
},
{
    "Id": "f25ecd70-0875-4dec-8afc-9228d8de0796",
    "type": "MyObject",
    "invoiceID__c": "8a9099d584ccc5180184cfe470277450",
    "mydata__c": "My Data 3",
    …
}

The first two records are linked to the context invoice of this event, and the third record is linked to another invoice.

The following table shows the values of merge fields in email or callout templates related to the Invoice Due event:

The resolved value of the same field can differ depending on the merge field type. For example, the system merge field {{Account.Currency}} returns currency codes such as USD and EUR, whereas the data source merge field {{DataSource.Account.Currency}} returns currency names such as US Dollar and Euro.