Articles in this section

dateAdd helper

Tom Santiago
Updated

Use {{dateAdd}} to add or subtract a specific time offset from a given date, optionally applying a time zone for the resulting ISO 8601 timestamp. Specify the offset in milliseconds, or use a readable interval (such as 1 "day") instead of converting to milliseconds yourself. Typical uses include adjusting a date by days/hours or converting a timestamp to a particular time zone.

Usage

{{dateAdd dateField offsetValue interval timeZoneField}}
  • dateField (required): The date to be adjusted (e.g., a string like "2025-03-26T00:00:00Z", or a reference like record.orderDate).
  • offsetValue (optional): A numeric offset. Combine it with interval to use readable units (e.g., 1 with "day"), or omit interval and provide the offset in milliseconds for the legacy behavior. Prepend a minus sign (-) to subtract instead of add. For example, 1 "day" = +1 day; -1 "day" = -1 day; "86400000" (legacy, no interval) = +1 day.

  • interval (optional): The unit for offsetValue. Tokens are case-sensitive unless using full names; default to milliseconds if you provide offsetValue, and whitespace is trimmed. If you use full names instead of the supported token values, both singular and plural forms are allowed, and the full names are case-insensitive (for example, day, days, Days, dAys, DAY). Supported tokens:

    • ms — milliseconds
    • s — seconds
    • min — minutes
    • h — hours
    • d — days
    • w — weeks
    • M — months
    • Y — years
  • timeZoneField (optional): A valid time zone identifier (e.g., "America/New_York", "Asia/Hong_Kong"). If omitted, the output remains in UTC with no specific offset.

How the third argument is interpreted

When you pass three arguments, {{dateAdd}} checks whether the third matches a supported interval token. If it does, it's read as interval; if it doesn't, it falls back to timeZoneField (legacy behavior). When you pass four arguments, the third is always interval and the fourth is always timeZoneField.

Note

Examples

  1. 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.

  2. Adding one day (legacy milliseconds)

    {{dateAdd record.orderDate "86400000"}}

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

  3. Adding one day using an interval

    {{dateAdd record.orderDate 1 "day"}}

    If record.orderDate is "2025-03-26T12:34:56Z", adds one calendar day and returns "2025-03-27T12:34:56.000Z".

  4. Subtracting twelve hours

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

    If record.shipDate is "2025-05-10T00:00:00Z", subtracts half a day, yielding "2025-05-09T12:00:00.000Z".

  5. Subtracting two hours using an interval, with a time zone

    {{dateAdd record.orderDate -2 "h" "America/New_York"}}

    If record.orderDate is "2025-03-26T12:00:00Z", subtracts two hours and shifts to New York time, resulting in "2025-03-26T06:00:00-04:00".

  6. Applying a time zone

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

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

  7. Hard-coded date string

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

    Outputs "2019-11-21T20:00:00.000Z" in ISO format.

Daylight saving time (DST) behavior

Calendar-based intervals (d, w, M, Y) add or subtract a calendar unit, landing on the same clock time on the target day even across a daylight saving time (DST) change. Duration-based intervals (ms, s, min, h) add or subtract a fixed span of time, so 24 "h" can land on a different clock time than 1 "day" when a DST transition falls in between and a time zone is applied. Offsets supplied without an interval are duration-based, too.

Because of this, replacing {{dateAdd date "86400000"}} with {{dateAdd date 1 "d"}} is not an exact swap; the two differ by an hour across a DST transition when a time zone is applied. Use 24 "h" to match the legacy result exactly, or 1 "d" for calendar-day semantics.

 

Error handling

If dateField can't be parsed, interval doesn't match a supported token, or offsetValue isn't numeric, {{dateAdd}} returns an empty string and logs an error. For an unsupported token, the error message lists the supported intervals.

Tip

  • Interval-based syntax (e.g., 1 "day") is easier to read than millisecond math and is recommended for new templates. Existing millisecond-based templates continue to work unchanged.
  • Offset values must be numeric (e.g., 86400000 for one day when using legacy milliseconds, or 1 when paired with an interval like "day"). Scientific notation (e.g., "1E6") is also supported for millisecond offsets.
  • Negative offsets (e.g., "-86400000" or -1 "day") subtract that time from the given date.
  • Time zones use IANA identifiers (e.g., "America/Los_Angeles"). If you omit this parameter, the result is in UTC.
  • The final output always conforms to an ISO 8601 date-time string, with or without the explicit offset depending on whether timeZoneField is provided.