Articles in this section

dateFormat helper

Tom Santiago
Updated

The dateFormat helper converts a date into a specified output format, and can optionally parse a custom input format and apply a time zone. Builders use it in Handlebars templates — including field mappings, response mappings, HTTP request bodies, and dynamic API paths — to reformat timestamps or convert them to a specific time zone.

Usage

{{dateFormat oFormat date iFormat timezone}}

oFormat -- The output format for the result, using moment.js format codes, for example "MM-DD-YYYY HH:mm" or "YYYY-MM-DDTHH:mm:ssZ". Required.

date -- The date to format, as a field reference such as record.orderDate or a date string. Required.

iFormat -- The format of the input date, using moment.js format codes, for example "YYYY-DD-MM HH:mm". Provide this when the input isn't in ISO 8601 or another automatically recognized format. Optional.

timezone -- A valid IANA time zone identifier, such as "America/Los_Angeles". When oFormat includes Z, the output shows the corresponding time zone offset. Optional.

Examples

Format an ISO date in US style

{{dateFormat "MM-DD-YYYY hh:mm A" record.orderDate}}

If record.orderDate is "2025-03-26T12:34:56Z", the output is "03-26-2025 12:34 PM".

Parse a custom input format

The day in "1966-25-05 18:36" is in the middle, so iFormat tells the helper how to read it.

{{dateFormat "MM-DD-YYYY HH:mm" record.orderDate "YYYY-DD-MM HH:mm"}}

If record.orderDate is "1966-25-05 18:36", the helper reads it as May 25, 1966 and outputs "05-25-1966 18:36".

Apply a time zone

{{dateFormat "YYYY-MM-DDTHH:mm:ssZ" record.orderDate "" "Asia/Hong_Kong"}}

This converts record.orderDate to Hong Kong time and includes the offset (+08:00) in the output, because oFormat ends with Z. The empty string for iFormat preserves the positional order so that timezone is read correctly.

Notes and constraints

  • Common tokens include YYYY (year), MM (month), DD (day), HH or hh (hour), mm (minute), ss (second), A or a (AM or PM), and Z (time zone offset). For the full list, see Time and date format codes.
  • Provide iFormat only when the input isn't in ISO 8601 or another recognized format. Omit it for standard ISO 8601 inputs.
  • When oFormat includes Z, the offset reflects the timezone you provide. Without a time zone, the result is in UTC.
  • Time zone identifiers use IANA naming, such as "America/New_York" or "Europe/London".
  • Because the parameters are positional, pass an empty string ("") for iFormat to specify a time zone without a custom input format.