Handlebar Helper Function: DateDiff

Calculates the time difference between two dates and returns the result in a specified unit. Use this helper to determine elapsed time in years, months, days, hours, minutes, or seconds.

This helper is available in the Summer ’26 release of Marketing Cloud Next (API version 67.0).

ParameterTypeDescription
date1String or ObjectRequired. The first date.
date2String or ObjectRequired. The second date.
intervalStringRequired. The unit of time to find between date1 and date2. Possible values: Y (years), M (months), D (days), H (hours), MI (minutes), S (seconds).

You can specify date1 and date2 in these formats:

  • US formats: MM/dd/yyyy, M/d/yyyy, MM/dd/yyyy HH:mm:ss, M/d/yyyy h:mm a, or M/d/yyyy h:mm:ss a

  • ISO formats: yyyy-MM-dd, yyyy-MM-dd HH:mm:ss, yyyy-MM-dd'T'HH:mm:ss, or yyyy-MM-dd'T'HH:mm:ss.SSSZ

  • 12-hour time: M/d/yyyy h:mm a, yyyy-MM-dd h:mm a, or yyyy-MM-dd h:mm:ss a

  • Time-only: h:mm a or h:mm:ss a

    If you specify only a time, the helper function uses the current date.

  • Long-form English: d MMMM yyyy, MMMM d, yyyy, or EEEE, MMMM d, yyyy

  • Chinese or Japanese notation: yyyy年M月d日

  • Korean notation: yyyy년 M월 d일 or yyyy년M월d일

ParameterTypeDescription
versionstringWhen set to "ampscript", the function counts the number of interval boundaries that have been crossed, as opposed to the full number of interval units.

The function returns an integer corresponding to the amount of time that elapsed between date1 and date2. For example, {{dateDiff 2025-12-26 2026-01-05 "D"}} returns 10, because there is a difference of ten days between the two dates.

The function counts complete elapsed units and truncates partial units. For example, {{dateDiff "2025-01-31" "2025-02-02" "M"}} returns 0, because there isn’t a full month between the two dates, even though they crossed a month boundary (from January to February).

In AMPScript mode (version="ampscript"), the function counts interval boundaries crossed between the two dates. For example, {{dateDiff "2025-01-31" "2025-02-02" "M" version="ampscript"}} returns 1, because the dates cross a month boundary, even though the two dates are only 2 days apart.