Date and Time Calculations: Adding, Subtracting, and Modifying Time Values

To add or subtract time from a date or datetime value, use datetime_add.

Syntax: @(datetime_add(date_or_datetime, amount, unit))

Examples:

• @(datetime_add("2017-01-15", 5, "D")) — adds 5 days to January 15, 2017
• @(datetime_add(fields.dob, -3, "M")) — subtracts 3 months from a date field

[CAPTURE: Show a message or action field using datetime_add with a date and unit.]

Tip: Use negative values to subtract time.

The following units are supported:

• Y — Years
• M — Months
• W — Weeks
• D — Days
• h — Hours
• m — Minutes
• s — Seconds

Note: Unit values are case-sensitive.

To replace the time portion of a datetime value, use replace_time.

Syntax: @(replace_time(datetime, time))

Examples:

• @(replace_time(now(), "10:30")) — returns today at 10:30 AM
• @(replace_time(contact.created_on, time("15:00"))) — keeps the creation date but sets the time to 3:00 PM

[CAPTURE: Show a message preview displaying a date with a replaced time value.]

Important: replace_time does not change the date—only the time.

You can use datetime_add to shift a datetime forward or backward in hours.

Example: @(datetime_add(contact.created_on, 15, "h")) — returns the datetime 15 hours after the contact was created.

[CAPTURE: Show a follow-up message scheduled using hour-based datetime arithmetic.]

To calculate the duration between two dates or datetimes, use datetime_diff.

Syntax: @(datetime_diff(date1, date2, unit))

Examples:

• @(datetime_diff("2017-01-15", "2017-01-17", "D")) — returns 2 days
• @(datetime_diff("2017-01-15", "2017-05-15", "W")) — returns 17 weeks
• @(datetime_diff("2017-01-15", "2017-05-15", "M")) — returns 4 months
• @(datetime_diff("2017-01-17 10:50", "2017-01-17 12:30", "h")) — returns 1 hour
• @(datetime_diff("2017-01-17", "2015-12-17", "Y")) — returns -2 years

[CAPTURE: Show a calculation result using datetime_diff with different units.]

Important: The result can be negative if the second date is earlier than the first.

Date & time arithmetic is often used to:

• Calculate age or elapsed time
• Schedule reminders relative to events
• Trigger flows after a delay
• Measure time between actions
• Format dynamic appointment messages

Important: Common mistakes to avoid:

• Using invalid or incorrectly-cased units (for example, "d" instead of "D")
• Forgetting quotation marks around date strings
• Mixing date formats inconsistently across expressions
• Expecting replace_time to change the date