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 also has also some things that you should be aware. 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')

Since the format is:

day.time.milliseconds

The function will return 171.00:00:00 because there are 171 days between January 1, 2025, and January 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 milliseconds 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. The milliseconds provide a level of precision that is reliable. We don’t have control over how fast and when Power Automate executes our Flow, so don’t trust the millisecond. 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 milliseconds. 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 milliseconds)
3. Only time parameter (with or without milliseconds)

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.

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.

Common Mistakes

Here are some common pitfalls when using the “dateDifference” function:

Ignoring timezones

The function calculates differences based on the dates provided precisely as they are. Your results may be unexpected if one date is in UTC and another in a local time zone. Always ensure both dates are in the same time zone before comparison. You can use the “convertTimeZone” function or “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.

Recommendations:

Here are some things to keep in mind when using the “dateDifference function”:

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.

Sources:

Microsoft’s dateDifference Function Reference

Back to the Power Automate Function Reference.

You can follow me on Mastodon (new account), Twitter (I’m getting out, but there are still a few people who are worth following) or LinkedIn. Or email works fine as well 🙂

Photo by Luba Ertel on Unsplash