Articles in this section

dateAdd helper

Tom Santiago
Updated

The dateAdd helper adds or subtracts a time offset, in milliseconds, from a date and returns the result as an ISO 8601 timestamp. You can also apply a time zone to the result. Builders use it in Handlebars templates — including field mappings, response mappings, HTTP request bodies, and dynamic API paths — to shift a date by a set duration or to convert a timestamp to a specific time zone.

Usage

{{dateAdd dateField offsetField timeZoneField}}

dateField -- The date to adjust, as an ISO 8601 string such as "2025-03-26T00:00:00Z" or a field reference such as record.orderDate. Required.

offsetField -- The time offset in milliseconds. Prepend a minus sign (-) to subtract instead of add. For example, "86400000" adds 1 day and "-86400000" subtracts 1 day. Scientific notation such as "1E6" is also supported. Optional.

timeZoneField -- A valid IANA time zone identifier, such as "America/New_York" or "Asia/Hong_Kong". If omitted, the result stays in UTC with no offset. Optional.

Examples

No offset or time zone

{{dateAdd record.orderDate}}

If record.orderDate is "2025-03-26T12:34:56Z", the output is "2025-03-26T12:34:56.000Z" in ISO 8601 UTC format.

Add 1 day

{{dateAdd record.orderDate "86400000"}}

If record.orderDate is "2025-03-26T12:34:56Z", the helper adds 24 hours and returns "2025-03-27T12:34:56.000Z".

Subtract 12 hours

{{dateAdd record.shipDate "-43200000"}}

If record.shipDate is "2025-05-10T00:00:00Z", the helper subtracts 12 hours and returns "2025-05-09T12:00:00.000Z".

Apply a time zone

{{dateAdd record.orderDate "86400000" "Asia/Hong_Kong"}}

If record.orderDate is "2025-03-26T00:00:00Z", the helper adds 24 hours and shifts the result to Hong Kong time, returning "2025-03-27T08:00:00.000+08:00".

Use a hard-coded date string

{{dateAdd "Mon Nov 21 2019 20:00:00 GMT+0000"}}

The output is "2019-11-21T20:00:00.000Z" in ISO 8601 format.

Notes and constraints

  • Offset values must be in milliseconds. For example, 86400000 milliseconds equals 1 day. Scientific notation such as "1E6" is also supported.
  • A negative offset, such as "-86400000", subtracts that duration from the date.
  • Time zones use IANA identifiers, such as "America/Los_Angeles". If you omit the time zone, the result is in UTC.
  • The output always conforms to an ISO 8601 date-time string. It includes an explicit time zone offset only when you provide timeZoneField.