Overview

MergeUp offers a simple datetime formatting function called dt, designed to streamline the process of formatting date and time values within your template documents. This function is highly flexible, allowing you to format Salesforce datetime merge field or any JavaScript-calculated datetime values. You can specify the desired locale in BCP 47 language tags, set the time zone, and configure time zone correction to ensure your datetime displays precisely as needed. In this comprehensive guide, we will cover the syntax, parameters, provide examples, and offer additional notes to help you make the most of this versatile function.

Syntax

{# dt(field, locale, timezone, useLocalTimezone) #}

Parameters

• field: Accepts a wide range of date and time values, including Salesforce datetime merge fields,  any JavaScript-calculated datetime values or string representations of dates that follow ISO-8601 format (strings must be in the yyyy-mm-ddThh:mm:ss.sssZ format).

• locale (optional): A BCP 47 language tag specifying the desired locale for formatting the date and time. Here is the full list of accepted values: BCP 47 Language Codes List - AppMakers.Dev

• timezone (optional): The time zone in which you want to display the date and time. In this article the "TZ identifier" column is the list of all accepted values: List of tz database time zones - Wikipedia

• useLocalTiezone (optional): Set to false to use the UTC time zone instead of your local time zone defined by your Salesforce org. Defaults to true.

Examples:

Example 1: Formatting a Merge Field

Suppose you have a template based on Salesforce opportunities and want to display the created date and time in your document. You can achieve this by doing the following:

{# dt(Opportunity.CreatedDate) #}

Assuming the template defines the locale as "en-US" and the created date was September 8, 2023, at around 10am, the output would be as follows:

9/8/2023, 10:06:06 AM

Example 2: Formatting a Calculated Date

You can also use the dt function to format JavaScript-calculated date values. For instance, if you want to include today's date in your template, you can define a new variable called today within an exec tag and then format it using your desired locale and time zone:

{#! today = new Date() #}
{# dt(today, 'en-US', 'America/New_York') #}

Assuming the document was merged on September 8, 2023, sometime around 4pm, the expected output of this function would be:

9/8/2023 4:58:08 PM

Example 3: Formatting an ISO - 8601 date string

Suppose you defined a variable in your template called myDatetimeString that holds a string that you constructed elsewhere in the template, and you want to display this in a standardized format. You can achieve this by doing the following:

let myDatetimeString = '2025-05-19T09:00:00.000Z'
{# dt(myDatetimeString) #}

Assuming the template defines the locale as "en-US", the output would be as follows:

5/19/2025, 9:00:00 AM

Example 4: Disabling time zone correction

Disable time zone correction for your datetime if needed. For example, assuming the current datetime is December 8, 2023, at 11 AM EST for your time zone, the time will be automatically corrected for your time zone.

{# dt(new Date()) #}
Results in: 12/8/2023 11:00:00 AM

You can disable this correction and use UTC time by passing false into the useLocalTimezone parameter (pass null into the locale and timezone parameters to continue to use the template's defaults):

{# dt(new Date(), null, null, false) #}
Results in: 12/8/2023 4:00:00 PM

We recommend leaving the useLocalTimezone parameter enabled when formatting datetimes based on the current time. For example:

{# dt(new Date()) #}

We recommend making the useLocalTimezone parameter disabled when dynamically constructing specific datetimes. For example:

{# dt(new Date(2023, 1, 1, 10, 30, 0), null, null, false) #}

Notes:

• If you don't specify a locale or time zone, the function will default to using the settings defined in your template or organization.
• If you pass in a plain date field, it will default to 00:00:00 as the time.