Salesforce Docs Portal

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

Availability

This helper is available in the Summer ’26 release of Marketing Cloud Next.

Syntax

{{dateDiff date1 date2 interval [version="ampscript"]}}

Parameters

Parameter Type Description
date1 String or Object Required. The first date.
date2 String or Object Required. The second date.
interval String Required. The unit of time to find between date1 and date2. Possible values: Y (years), M (months), D (days), H (hours), MI (minutes), S (seconds).

Date Input

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

    note: 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일

Hash Parameters

Parameter Type Description
version string When set to "ampscript", the function counts the number of interval boundaries that have been crossed, as opposed to the full number of interval units.

Return Value

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.