Define date and numeric formats for Mail Merge fields
Format merge fields using Mail Merge switches
To format a merge field, complete the following steps:
- In the template document, while the merge field is selected, do the following to display the field code:
- Press Shift + F9 on Windows.
- Press Fn + Shift + F9 on Mac.
- Remove "
\*
MERGEFORMAT
" from the field code. - Enter the switch in the field code. For example:
- Original field code:
{MERGEFIELD myObject.myField \*MERGEFORMAT
}
- Updated field code:
{MERGEFIELD
myObject.myField \# ###,###,###,#00.0}
- Original field code:
- Update the field:
- Press F9 on Windows.
- Press Fn + F9 on Mac.
To format a numeric merge field, use the \#
switches. For example, to display a currency field as "$125.23", the merge field should be defined as {MERGEFIELD myObject.myField \# $#,##0.00}
.
To format a date merge field, use the \@ switches. For example, to display a date field as "03/30/2010", the merge field should be defined as { MERGEFIELD myObject.myField \@ MM/dd/yyyy}
.
To generate billing documents with specific currency symbols, you must create separate billing document templates for each currency and include the MERGEFORMAT using examples described in the following table. See How do I handle Multi-currency in Zuora for more information.
Date and numeric format examples
For merge fields in date formats, yyyy
and YYYY
might be different for the same date or timestamp.yyyy
represents the calendar year of the date while YYYY
represents the year of the week.
For example, the calendar year of date 2020–12–28 is 2020; on the other hand, the date is Monday, the first day and first week of the year 2021. For the date, the year of the week is 2021. If you use yyyy
as the date format, the displayed year for 2020–12–28 is 2020. If you use YYYY
as the date format, the displayed year for 2020–12–28 is 2021.
Therefore, It is best practice to always use as the yyyy
format for date merge fields.
The following table includes formatting examples for the date and number types mail merge fields.
Field format | Merge field syntax |
---|---|
To use standard date formatting: 10/26/2012 |
|
To use simple date formatting: 20121026 |
{MERGEFIELD Invoice.InvoiceDate \@ yyyyMMdd} |
To use text date formatting: OCT 2012 |
The rendering result of the
|
To use standard percentage formatting: 0.08 |
{MERGEFIELD TaxItem.TaxRate} |
To use percentage symbol formatting: 8% |
{MERGEFIELD TaxItem.TaxRate \# ##%} |
To specify a label for a quantity: 3.0000kg |
{MERGEFIELD Usage.Quantity \# #,##0.0000kg} |
To specify a symbol for a currency: €12,13.8 |
{MERGEFIELD Invoice.Total \# €#,#0.0} |
Numeric merge field formatting based on communication profiles
When defining templates for invoices, credit memos, and debit memos, you can also format numeric merge fields based on your customers' communication profile locales. To enable this feature, complete the followings steps:
- Click your username at the upper right and navigate to Settings > Billing > Define Billing Rules.
- On the Billing Rules page, click edit.
- Select Yes from the Format numeric merge fields based on communication profile locales? list.
- Click save.
The following table includes formatting examples for numeric merge fields based on different communication profile locales.
Merge Field Syntax | Field Value | Communication Profile | Rendering Result |
---|---|---|---|
{MERGEFIELD Invoice.Total \# #,##0.00} |
123456789.000 | US | 123,456,789.00 |
ITALY | 123.456.789,00 | ||
FRANCE | 123 456 789,00 |
The thousands separator might be different based on different communication profile locales.
Merge Field Syntax | Field Value | Communication Profile | Rendering Result without This Feature | Rendering Result with This Feature |
---|---|---|---|---|
{MERGEFIELD Invoice.Total \# ,#.00} |
1234.000 | US | 1,234.00 | 1,2,3,4.00 |
In the preceding case, you have to change the merge field syntax to {MERGEFIELD Invoice.Total \# ,###.00}
to have the expected rendering result 1,234.00 with this feature.