Power Automate: dateDifference function

The "dateDifference" function is a powerful tool for when you need to calculate the difference between two dates. It gives you a reliable way to get the day and time difference between two dates, but it also has some things that you should be aware of. Let's dive into how it works, explore practical examples, and learn how to avoid common pitfalls.

Where to find it?

You can find the function in every action where a formula is supported. For example, let's look at a "Compose" action:

As you can see, we can auto-complete by using the "tab" key (old UI) or "enter" key (new UI). Let's look at how to use it.

Usage

The "dateDifference" function follows a specific pattern with two required parameters:

dateDifference(<timestamp1>, <timestamp2>)

Let's start with a simple example where we calculate the number of days between two dates:

dateDifference('2025-01-01','2025-06-21')

It helps to know the exact shape of the result. The function always hands you back a string in this form:

[-][days.]hours:minutes:seconds[.fractionalSeconds]

You get an optional minus sign, an optional day count (only shown when there is at least one full day), then hours, minutes, and seconds, and finally an optional fractional part. That single shape explains every quirk we are about to see.

The function will return 171.00:00:00 because there are 171 days between January 1, 2025, and June 21, 2025.

Notice the .00:00:00 after the number of days. We'll get back to that, but I wanted to give you a general example of the result.

Dynamic Values

You can also use dynamic date values, such as the current time:

dateDifference('2025-01-01', utcNow())

This will calculate the number of days between January 1, 2025, and the current date (at the time of writing, it was March 6th, 2025, 17:19 CET). Here's the result.

Let's parse it. The first part is the number of days, like before. So we will have 64 days until the date. But notice the next part. It's the number of hours, minutes, seconds, and fractional seconds between the dates.

The output of the "dateDifference" function is a string, so you need to parse the results. One can think that a quick "split" function can do the trick, but not always (see below). If we have the value in a "Compose" action called "Compose_1" then the formula is as follows:

split(outputs('Compose_1'),'.')

You will get an array as follows.

Then you know that the first element of the array is the number of days, and the second is the time component. You can safely ignore the third part for two reasons. It holds fractional seconds, a level of precision we rarely need. We also don't have control over how fast and when Power Automate executes our Flow, so don't trust that part. Also, if you need this level of precision, then you should probably use another tool. The second reason is that sometimes it is not even returned. Notice the first example; the time component was returned .00:00:00, so another good reason to ignore it.

But this doesn't always work, and here's why.

What if we have the same day with different times?

When using just dates without time (e.g., '2025-01-01'), Power Automate assumes 00:00:00 (midnight) as the time, like this.

dateDifference('2025-01-01', '2025-01-01T12:00:00Z')

This will return 12:00:00

Notice that the "days" component will not be returned.

So, the "split" function before won't work since the first element won't always be the day, and the 3rd won't always be the fractional seconds. In this case, it won't even be returned, so we need a better strategy.

How to properly process it?

I will show you a strategy, but if you have a better one, please get in touch by email or in the comments. I'll publish any strategy that I feel is better for everyone.

There isn't a great strategy to get the values because each time the function returns, the values are not deterministic, as we've seen before. So if you can get:

1. Only days
2. Days and time parameters (with or without fractional seconds)
3. Only time parameter (with or without fractional seconds)

So, we need to process the values so that we can get them individually based on all these potential cases. Let's find a formula that works by splitting it in two: one that gets the date and one that gets the time.

To demonstrate how they work, let's build a test workflow.

We have the first "Compose" action that contains the "dateDifference" function, like this, for example:

dateDifference('2025-01-01', '2025-01-02T12:00:01Z')

The second "Compose" action will split the data as before, and the next two will get the date and time, respectively.

Let's look at the second "Compose" action.

split(outputs('Test_Date_Difference'),'.')

The above function will return.

1.12:00:01

And when we split it we get:

The day part

Here's the formula that extracts the day. It contains a few validations to protect it against potential invalid values.

if(equals(length(outputs('Split_the_values')),0),'0',if(contains(outputs('Split_the_values')[0],':'),'0',outputs('Split_the_values')[0]))

What we're doing here?

1. With the "length" function, we check if we get any values. If the split doesn't return anything, we should return 0 days. You can return any value that makes sense to you.
2. With the "if" function, we will check if the first element (it's safe to do since we checked if the array has elements before) contains (using the "contains" function) the character ":". If it does, then we know that the first element of the array is a time, so we can safely return zero since it's the same day. If not, then we know we have a day to return so we will return it.

So far, so good, but your eagle-eyed readers noticed something strange in the function. The days are a number, so why are we returning '0' (a string) instead of 0 (a number)? Well, in Power Automate, zero can be interpreted as false, so if you return it, it will return an empty value. Don't believe me? Let's replace in the first "Compose" action with:

dateDifference('2025-01-01', '2025-01-01T12:00:01Z')

And the function with numeric zeros.

if(equals(length(outputs('Split_the_values')),0),0,if(contains(outputs('Split_the_values')[0],':'),0,outputs('Split_the_values')[0]))

Here's the result:

So it's important to protect against this case and save you some headaches.

Now that you know how to get the day part, let's look at the time part.

The time part

The time part works in a similar way as the day part. When we split, we will get the array, so we need to perform a similar validation:

if(equals(length(outputs('Split_the_values')),0),'00:00:00',if(contains(outputs('Split_the_values')[0],':'),outputs('Split_the_values')[0],outputs('Split_the_values')[1]))

What we're doing here?

1. With the "length" function, we check to see if we get any values at all. It's possible that the split won't return anything, so we should return 00:00:00 because it's the same time. This often happens when we're comparing dates only with the date part.
2. With the "if" function, we will check if the first element (it's safe to do since we checked if the array has elements before) contains (using the "contains" function) the character ":". If it does, then we know that the first element of the array is a time, so we can safely return it since that's what we want. If not, then we know we have a day, so we return the second element of the array.

That's it.

Non-intuitive behaviors

Here are some behaviors that can catch you off guard when using the "dateDifference" function.

Ignoring timezones

The function calculates differences based on the dates provided precisely as they are. It doesn't normalize anything; it compares the two instants exactly as they are parsed. So your results may be unexpected if one date is in UTC and another in a local time zone, and a value ending in "Z" compared against a naive local string is the classic source of "off by a few hours" bugs. It also doesn't adjust for daylight saving on its own. Always make sure both dates are in the same time zone before you compare them. You can normalize them first with the "convertTimeZone" function or the "Convert a time zone" action.

Swapping Start and End Dates

One common mistake is swapping the order of dates. The function will return a negative value if your end date is before your start date. Some users assume it will automatically swap the dates, but it won't:

// This will return -14.00:00:00
dateDifference('2025-01-15', '2025-01-01')

If you always want a positive value, you can use the "abs function" after you break it into pieces to get the value you need, but a better solution would always be to ensure that the dates are in the correct order unless you want the value to be negative, of course.

Limitations

There are a few things to be aware of when using the "dateDifference" function.

Expression Size Limits

As with all Power Automate expressions, there's a limit of 8,192 characters. If you're building complex date calculations, try to break them up into smaller, manageable pieces using variables.

The result is a string, not a number

You can't do maths directly on the output. Parse it first, or use the "ticks" approach from the recommendations below when you need a number.

Troubleshooting Common Errors

Invalid timestamp errors

Symptom: You get an InvalidTemplate error saying the value could not be parsed. Cause: One of the inputs isn't a valid ISO 8601 timestamp, for example 19/03/2026. Solution: Convert it to a proper timestamp first with the "formatDateTime" or "parseDateTime" function before calling "dateDifference".

The result is off by a few hours

Symptom: The difference is several hours larger or smaller than you expect. Cause: One date carries a "Z" (UTC) suffix and the other doesn't, so they're parsed as different instants. Solution: Make sure both dates are in the same time zone before comparing them.

Recommendations

Here are some things to keep in mind when using the "dateDifference" function.

Prefer "ticks" for reliable day counts

Because the day part disappears for short spans and the string is fiddly to parse, the most robust way to count whole days is to skip the string entirely and use the "ticks" function. Ticks are a simple count of 100-nanosecond intervals, so subtracting one from the other and dividing gives you a clean number:

div(sub(ticks(<endDate>), ticks(<startDate>)), 864000000000)

There are 864,000,000,000 ticks in a day, so this returns the number of whole days. It sidesteps the missing-days case and isn't affected by daylight saving shifts.

Use "debug" compose actions

When building complex date calculations, use Compose actions as intermediate steps to see the values. This makes it easier to debug if something doesn't work as expected.

Validate your dates

Before calculating differences, ensure your date values are valid and in the format you expect. Try using a Compose actions to output each date value first, so you know what you're working with.

Be consistent with time zones

Always ensure both dates are in the same time zone before comparison. Use the "convertTimeZone" function when needed to normalize your dates.

Always add a comment

Adding a comment will help you and others understand your intention. Explain why you're calculating the date difference and how the result will be used. What might be obvious today may not be in a few months.

Final Thoughts

The "dateDifference" function is handy for quick gaps between two dates, as long as you remember that it hands you back a string and that the day part can disappear on short spans. Parse it carefully, keep your time zones consistent, and when you just need a clean number, reach for the "ticks" approach. Get those right and it'll serve you well.

Sources

• Microsoft's dateDifference function reference

Back to the Power Automate Function Reference

Photo by Luba Ertel on Unsplash