# 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

```handlebars
{{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.