Using Date and Date/Time in
Formulas
Salesforce, Winter ’25
Last updated: July 25, 2024
©
Copyright 2000–2024 Salesforce, Inc. All rights reserved. Salesforce is a registered trademark of Salesforce, Inc., as are other
names and marks. Other marks appearing herein may be trademarks of their respective owners.
USING DATE, DATE/TIME, AND TIME VALUES IN FORMULAS
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: All Editions
Date formulas are useful for managing payment deadlines, contract ages, or any other features of
your organization that are time or date dependent.
Two data types are used for working with dates: Date and Date/Time. One data type, Time, is
independent of the date for tracking time such as business hours. Most values that are used when
working with dates are of the Date data type, which store the year, month, and day. Some fields,
such as CreatedDate, are Date/Time fields, meaning they not only store a date value, but also a time
value (stored in GMT but displayed in the users’ time zone). Date, Date/Time, and Time fields are
formatted in the user’s locale when viewed in reports and record detail pages. A Time value’s
precision is in milliseconds. A Date/Time value’s precision is in seconds.
You can use operations like addition and subtraction on Date, Date/Time, and TIme values to calculate a future date or elapsed time
between two dates or times. If you subtract one date from another, for example, the resulting value will be the difference between the
two initial values in days (Number data type). The same operation between two Date/Time values returns a decimal value indicating
the difference in number of days, hours, and minutes. The same operation between two Time values returns millisecond
For example, if the difference between two Date/Time values is 5.52, that means the two values are separated by five days, 12 hours (0.5
of a day), and 28 minutes (0.02 of a day). You can also add numeric values to Dates and Date/Times. For example, the operation TODAY()
+ 3 returns three days after today’s date. For more information and examples of working with dates, see the list of Sample Date Formulas.
Throughout the examples, the variables date and date/time are used in place of actual Date and Date/Time fields or values.
Keep in mind that complex date functions tend to compile to a larger size than text or number formula functions, so you might run into
issues with formula compile size. See Tips for Reducing Formula Size for help with this problem.
TODAY(), NOW() and TIMENOW()
The TODAY() function returns the current day, month, and year as a Date data type. This function is useful for formulas where you are
concerned with how many days have passed since a previous date, the date of a certain number of days in the future, or if you just want
to display the current date.
The NOW() function returns the Date/Time value of the current moment. It’s useful when you are concerned with specific times of day
as well as the date.
The TIMENOW() function returns a value in GMT representing the current time without the date. Use this function instead of the
NOW() function if you want the current hour, minute, seconds, or milliseconds. This value is useful for tracking time like work shifts or
elapsed time,
For details on how to convert between Date values and Date/Time values, see Converting Between Date/Time and Date on page 2.
The DATE() Function
The DATE() function returns a Date value, given a year, month, and day. Numerical Y/M/D values and the YEAR(), MONTH(), and
DAY() functions are valid parameters for DATE(). For example DATE( 2013, 6, 1 ) returns June 1, 2013. Similarly, DATE(
YEAR( TODAY() ), MONTH( TODAY() ) + 3, 1) returns the Date value of the first day three months from today in the
current year, assuming the date is valid (for example, the month falls between 1 and 12).
1
If the inputted Y/M/D values result in an invalid date, the DATE() function returns an error, so error checking is an important part of
working with Date values. You can read about methods for handling invalid dates in Sample Date Formulas.
Converting Between Date/Time and Date
Date and Date/Time aren’t interchangeable data types, so when you want to perform operations between Date and Date/Time values,
you need to convert the values so they are both the same type. Some functions (such as YEAR(), MONTH(), and DAY()) also only
work on Date values, so Date/Time values must be converted first.
Use the DATEVALUE( date/time ) function to return the Date value of a Date/Time. For example, to get the year from a
Date/Time, use YEAR( DATEVALUE( date/time ) ) ).
You can convert a Date value to a Date/Time using the DATETIMEVALUE( date ) function. The time will be set to 12:00 a.m. in
Greenwich Mean Time (GMT), and then converted to the time zone of the user viewing the record when it’s displayed. For a user located
in San Francisco, DATETIMEVALUE( TODAY() ) returns 5:00 p.m. on the previous day (during Daylight Saving Time) rather than
12:00 a.m. of the current day. See A Note About Date/Time and Time Zones on page 3 for more information.
Converting Between Date/Time and Time
The TIMEVALUE() function returns a Time data type value in “HH:MM:SS.MS” (hours:minutes:seconds.milliseconds) format using a
24-hour clock. Numerical H/M/S/MS values and the HOUR(), MINUTE(), SECONDS(), and MILLISECONDS() functions are
valid parameters for TIMEVALUE().
Use the TIMEVALUE(value) function to return the Time value of a Date/Time type, text, merge field or expression. For example,
extract the time from a ClosedDate Date/Time value with TIMEVALUE(ClosedDate).
Converting Between Date and Text
If you want to include a date as part of a string, wrap the Date value in the TEXT() function to convert it to text. For example, if you
want to return today’s date as text, use:
"Today's date is " & TEXT( TODAY() )
This returns the date in the format “YYYY-MM-DD” rather than in the locale-dependent format. You can change the format by extracting
the day, month, and year from the date first and then recombining them in the format you want. For example:
"Today's date is " & TEXT( MONTH( date ) ) & "/" & TEXT( DAY( date ) ) & "/" & TEXT( YEAR(
date ) ) )
You can also convert text to a Date so you can use the string value with your other Date fields and formulas. You’ll want your text to be
formatted as “YYYY-MM-DD”. Use this formula to return the Date value:
DATEVALUE( "YYYY-MM-DD" )
Converting Between Date/Time and Text
You can include Date/Time values in a string using the TEXT() function, but you need to be careful of time zones. For example,
consider this formula:
"The current date and time is " & TEXT( NOW() )
2
Using Date, Date/Time, and Time Values in Formulas
In this formula, NOW() is offset to GMT. Normally, NOW() would be converted to the user’s time zone when viewed, but because it’s
been converted to text, the conversion won’t happen. So if you execute this formula on August 1st at 5:00 PM in San Francisco time
(GMT-7), the result is “The current date and time is 2013–08–02 00:00:00Z”.
When you convert a Date/Time to text, a “Z” is included at the end to indicate GMT. TEXT( date/time ) returns “Z” if the field is
blank. So if the Date/Time value you’re working with might be blank, check for this before converting to text:
IF(
ISBLANK( date/time ),
"",
TEXT( date/time )
)
To convert a string to a Date/Time value, use DATETIMEVALUE() passing in a string in the format “YYYY-MM-DD HH:MM:SS”. This
method returns the Date/Time value in GMT.
Converting Between Time and Text
If you want to include time as part of a string, wrap the Time value in the TEXT() function to convert it to text. For example, if you
want to return the current time as text, use:
"The time is " & TEXT( TIMENOW() )
This function returns the time in the format “HH:MM:SS.MS”.
You can also convert text to a Time data type so you can use the string value with your other Time fields and formulas. Format your text
as “HH:MM:SS.MS” on a 24-hour clock. Use the TIMEVALUE() function:
TIMEVALUE("17:30:45.125")
A Note About Date/Time and Time Zones
Date and Date/Time values are stored in GMT. When a record is saved, field values are adjusted from the user’s time zone to GMT, and
then adjusted back to the viewer’s time zone when displayed in record detail pages and reports. With Date conversions this doesn't
pose a problem, since converting a Date/Time to a Date results in the same Date value.
When working with Date/Time fields and values, however, the conversion is always done in GMT, not the user’s time zone. Subtracting
a standard Date/Time field from another isn’t a problem because both fields are in the same time zone. When one of the values in the
calculation is a conversion from a Text or Date value to a Date/Time value, however, the results are different.
Let’s say a San Francisco user enters a value of 12:00 AM on August 2, 2013 in a custom Date/Time field called Date_Time_c. This
value is stored as 2013–08–02 07:00:00Z, because the time difference in Pacific Daylight Time is GMT-7. At 12:00 p.m. PDT on August
1st, the user views the record and the following formula is run:
Date_Time_c - NOW()
In the calculation, NOW() is 2013–08–01 19:00:00Z, and then subtracted from 2013–08–02 07:00:00Z, to return the expected result of
0.5 (12 hours).
Suppose that instead of NOW(), the formula converts the string “2013–08–01 12:00:00” to a Date/Time value:
Date_Time_c - DATETIMEVALUE( "2013-08-01 12:00:00" )
In this case, DATETIMEVALUE( “2013–08–01 12:00:00” ) is 2013–08–01 12:00:00Z, and returns a result of 0.79167, or
19 hours.
3
Using Date, Date/Time, and Time Values in Formulas
There’s no way to determine a user’s time zone in a formula. If all of your users are in the same time zone, you can adjust the time zone
difference by adding or subtracting the time difference between the users’ time zone and GMT to your converted values. However, since
time zones can be affected by Daylight Saving Time, and the start and end dates for DST are different each year, this is difficult to manage
in a formula. We recommend using Apex for transactions that require converting between Date/Time values and Text or Date values.
4
Using Date, Date/Time, and Time Values in Formulas
SAMPLE DATE FORMULAS
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: All Editions
Use the sample formulas in this topic to manipulate and perform calculations with date and time.
Find the Day, Month, or Year from a Date
Use the functions DAY( date ), MONTH( date ), and YEAR( date ) to return their
numerical values. Replace date with a value of type Date (for example, TODAY()).
To use these functions with Date/Time values, first convert them to a date with the DATEVALUE()
function. For example, DAY( DATEVALUE( date/time )).
Find Out If a Year Is a Leap Year
This formula determines whether a year is a leap year. A year is only a leap year if it’s divisible by 400, or if it’s divisible by four but not by
100.
OR(
MOD( YEAR( date ), 400 ) = 0,
AND(
MOD( YEAR( date ), 4 ) = 0,
MOD( YEAR( date ), 100 ) != 0
)
)
Find Which Quarter a Date Is In
For standard quarters, you can determine which quarter a date falls in using this formula. This formula returns the number of the quarter
that date falls in (1–4) by dividing the current month by three (the number of months in each quarter) and taking the ceiling.
CEILING( MONTH ( date ) / 3 )
The formula for shifted quarters is similar, but shifts the month of the date by the number of months between January and the first
quarter of the fiscal year. The following example shows how to find a date’s quarter if Q1 starts in February instead of January.
CEILING( ( MONTH ( date ) - 1 ) / 3)
ITo check whether a date is in the current quarter, add a check to compare the date’s year and quarter with TODAY()’s year and quarter.
AND(
CEILING( MONTH( date ) / 3 ) = CEILING( MONTH( TODAY() ) / 3 ),
YEAR( date ) = YEAR( TODAY() )
)
5
Find the Week of the Year a Date Is In
To find the number of a date’s week of the year, use this formula:
IF(
CEILING( ( date - DATE( YEAR( date ), 1, 1) + 1) / 7) > 52,
52,
CEILING( ( date - DATE( YEAR( date ), 1, 1) + 1) / 7)
)
To find the current week number, determine the days to date in the current year and divide that value by 7. The IF() statement ensures
that the week number the formula returns doesn’t exceed 52. So if the given date is December 31 of the given year, the formula returns
52, even though it’s more than 52 weeks after the first week of January.
Find Whether Two Dates Are in the Same Month
To determine whether two Dates fall in the same month, say for a validation rule to determine whether an opportunity Close Date is in
the current month, use this formula:
AND(
MONTH( date_1 ) == MONTH( date_2 ),
YEAR( date_1 ) == YEAR( date_2 )
)
Find the Last Day of the Month
The easiest way to find the last day of a month is to find the first day of the next month and subtract a day.
IF(
MONTH( date ) = 12,
DATE( YEAR( date ), 12, 31 ),
DATE( YEAR( date ), MONTH ( date ) + 1, 1 ) - 1
)
Display the Month as a String instead of a Number
To return the month as a text string instead of a number, use:
CASE(
MONTH( date ),
1, "January",
2, "February",
3, "March",
4, "April",
5, "May",
6, "June",
7, "July",
8, "August",
9, "September",
6
Sample Date Formulas
10, "October",
11, "November",
"December"
)
If your organization uses multiple languages, you can replace the names of the month with a custom label:
CASE(
MONTH( date ),
1, $Label.Month_of_Year_1,
2, $Label.Month_of_Year_2,
3, $Label.Month_of_Year_3,
4, $Label.Month_of_Year_4,
5, $Label.Month_of_Year_5,
6, $Label.Month_of_Year_6,
7, $Label.Month_of_Year_7,
8, $Label.Month_of_Year_8,
9, $Label.Month_of_Year_9,
10, $Label.Month_of_Year_10,
11, $Label.Month_of_Year_11,
$Label.Month_of_Year_12
)
Find and Display the Day of the Week from a Date
To find the day of the week from a Date value, use a known Sunday, for example, January 7, 1900, and subtract it from the date, for
example, TODAY(), to get the difference in days. The MOD() function finds the remainder of this result when divided by 7 to give
the numerical value of the day of the week between 0 (Sunday) and 6 (Saturday). This formula finds the result and then returns the text
name of that day.
CASE(
MOD( date - DATE( 1900, 1, 7 ), 7 ),
0, "Sunday",
1, "Monday",
2, "Tuesday",
3, "Wednesday",
4, "Thursday",
5, "Friday",
"Saturday"
)
This formula only works for dates after 01/07/1900. If you work with older dates, use the same process with any Sunday before to your
earliest date, for example, 01/05/1800.
You can adjust this formula if your week starts on a different day. For example, if your week starts on Monday, you can use January 8,
1900 in your condition. The new formula looks like this:
CASE(
MOD( date - DATE( 1900, 1, 8 ), 7 ),
0, "Monday",
1, "Tuesday",
2, "Wednesday",
3, "Thursday",
4, "Friday",
7
Sample Date Formulas
5, "Saturday",
"Sunday"
)
To get the formula for the name of the month, if your organization uses multiple languages, you can replace the names of the day of
the week with a variable like $Label.Day_of_Week_1, and so on.
Find the Next Day of the Week After a Date
To find the date of the next occurrence of a particular day of the week following a given Date, get the difference in the number of days
of the week between a date and a day_of_week, a number 0–6 where 0 = Sunday and 6 = Saturday. By adding this difference to
the current date, you can find the date of the day_of_week. The IF() statement in this formula handles cases where the
day_of_week is before the day of the week of the date value (for example date is a Thursday and day_of_week is a Monday)
by adding 7 to the difference.
date + ( day_of_week - MOD( date - DATE( 1900, 1, 7 ), 7 ) )
+
IF(
MOD( date - DATE( 1900, 1, 7 ), 7 ) >= day_of_week,
7,
0
)
You can substitute either a constant or another field in for the day_of_week value based on your needs.
Find the Number of Days Between Two Dates
To find the number of days between two dates, date_1, and date_2, subtract the earlier date from the later date: date_1 —
date_2
You can alter this formula slightly if you want to determine a date that’s a certain number of days in the past. For example, to create a
formula to return true if some date field is more than 30 days before the current date and false otherwise, use a formula such as the
following:
TODAY() - 30 > date
Find the Number of Weekdays Between Two Dates
Calculating how many weekdays passed between two dates is slightly more complex than calculating total elapsed days. In this example,
weekdays are Monday through Friday. The basic strategy is to choose a reference Monday from the past and find out how many full
weeks and any additional portion of a week have passed between the reference date and your date. These values are multiplied by five
for a five-day work week, and then the difference between them is taken to calculate weekdays.
(5 * ( FLOOR( ( date_1 - DATE( 1900, 1, 8) ) / 7 ) ) + MIN( 5, MOD( date_1 - DATE( 1900,
1, 8), 7 ) ) )
-
(5 * ( FLOOR( ( date_2 - DATE( 1900, 1, 8) ) / 7 ) ) + MIN( 5, MOD( date_2 - DATE( 1900,
1, 8), 7 ) ) )
8
Sample Date Formulas
In this formula, date_1 is the more recent date and date_2 is the earlier date. If your work week runs shorter or longer than five
days, replace all fives in the formula with the length of your week.
Find the Number of Months Between Two Dates
To find the number of months between two dates, subtract the year of the earlier date from the year of the later date and multiply the
difference by 12. Next, subtract the month of the earlier date from the month of the later date, and add that difference to the value of
the first set of operations.
((YEAR(date_1) - YEAR(date_2))*12) + (MONTH(date_1) - MONTH(date_2))
Add Days, Months, and Years to a Date
If you want to add a certain number of days to a date, add that number to the date directly. For example, to add 5 days to a date, the
formula is date + 5.
If you want to add a certain number of months to a date, use this function.
ADDMONTHS()
For example, if you want to add 4 months to a date, use this formula.
ADDMONTHS(date + 4)
If the date that you provide is the last of any month, this formula returns the last day of the resulting month.
To add a certain number of years to a date, use this formula.
ADDMONTHS(date, 12*num_years)
If the date that you provide is February 29, and the resulting year isn’t a leap year, the formula returns the date as February 28. In this
scenario, if you want the resulting date as March 1, use this formula.
IF( MOD((Year (ADDMONTHS(date, 12* num_years)-1960),4)=0, ADDMONTHS(date,12*
num_years)+1,ADDMONTHS(date, 12*num_years))
Add Business Days to a Date
This formula finds three business days from a given date.
CASE(
MOD( date - DATE( 1900, 1, 7 ), 7 ),
3, date + 2 + 3,
4, date + 2 + 3,
5, date + 2 + 3,
6, date + 1 + 3,
date + 3
)
This formula finds the day of the week of the date field value. If the date is a Wednesday, Thursday, or Friday, the formula adds five
calendar days, two weekend days, three weekdays, to the date to account for the weekend. If date is a Saturday, you need four
9
Sample Date Formulas
additional calendar days. For any other day of the week Sunday Tuesday, simply add three days. You can easily modify this formula to
add more or fewer business days. The tip for getting the day of the week is useful to use to adjust this formula.
Find the Hour, Minute, or Second from a Date/Time
To get the hour, minute, and second from a Date/Time field as a numerical value, use the following formulas where TZoffset is the
difference between the user’s time zone and GMT. For hour in 24–hour format:
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) )
For hour in 12–hour format:
IF(
OR(
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) ) = 0,
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) ) = 12
),
12,
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) )
-
IF(
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) ) < 12,
0,
12
)
)
For minutes:
VALUE( MID( TEXT( date/time - TZoffset ), 15, 2 ) )
For seconds:
VALUE( MID( TEXT( date/time - TZoffset ), 18, 2 ) )
And, to get “AM” or “PM” as a string, use:
IF(
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) ) < 12,
"AM",
"PM"
)
To return the time as a string in “HH:MM:SS A/PM” format, use the following formula:
IF(
OR(
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) ) = 0,
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) ) = 12
),
"12",
TEXT( VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) )
-
IF(
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) ) < 12,
10
Sample Date Formulas
0,
12
)
)
)
& ":" &
MID( TEXT( date/time - TZoffset ), 15, 2 )
& ":" &
MID( TEXT( date/time - TZoffset ), 18, 2 )
& " " &
IF(
VALUE( MID( TEXT( date/time - TZoffset ), 12, 2 ) ) < 12,
"AM",
"PM"
)
When working with time in formula fields, always consider the time difference between your organization and GMT. See A Note About
Date/Time and Time Zones on page 3 for more information about the time zone offset used in this formula.
Find the Elapsed Time Between Date/Times
To find the difference between two Date values as a number, subtract one from the other like so: date_1 — date_2 to return the
difference in days.
Finding the elapsed time between two Date/Time values is slightly more complex. This formula converts the difference between two
Date/Time values, datetime_1 and datetime_2, to days, hours, and minutes.
IF(
datetime_1 - datetime_2 > 0 ,
TEXT( FLOOR( datetime_1 - datetime_2 ) ) & " days "
& TEXT( FLOOR( MOD( (datetime_1 - datetime_2 ) * 24, 24 ) ) ) & " hours "
& TEXT( ROUND( MOD( (datetime_1 - datetime_2 ) * 24 * 60, 60 ), 0 ) ) & " minutes",
""
)
Find the Number of Business Hours Between Two Date/Times
The formula to find business hours between two Date/Time values expands on the formula to find elapsed business days. It works on
the same principle of using a reference Date/Time. In this case 1/8/1900 at 16:00 GMT, or 9:00 AM PDT, and then finding your Dates’
respective distances from that reference. The formula rounds the value it finds to the nearest hour and assumes an 8–hour, 9:00 AM5:00
PM work day.
ROUND( 8 * (
( 5 * FLOOR( ( NOW() - DATETIMEVALUE( '1900-01-08 16:00:00') ) / 7) +
MIN(5,
FLOOR ( MOD ( NOW() - DATETIMEVALUE( '1900-01-08 16:00:00'), 7) / 1) +
MIN( 1, 24 / 8 * ( MOD( NOW () - DATETIMEVALUE( '1900-01-08 16:00:00' ), 1 ) ) )
)
)
-
( 5 * FLOOR( ( MQL_datetime_c - DATETIMEVALUE( '1900-01-08 16:00:00') ) / 7) +
11
Sample Date Formulas
MIN( 5,
FLOOR( MOD( MQL_datetime_c - DATETIMEVALUE( '1900-01-08 16:00:00'), 7) / 1) +
MIN( 1, 24 / 8 * ( MOD( MQL_datetime_c - DATETIMEVALUE( '1900-01-08 16:00:00' ), 1)
) )
)
)
),
2 )
You can change the eights in the formula to account for a longer or shorter work day. If you live in a different time zone or your work
day doesn’t start at 9:00 AM, change the reference time to the start of your work day in GMT. See A Note About Date/Time and Time
Zones for more information.
12
Sample Date Formulas
