Holidays
Holidays is the Salesforce Setup configuration that records non-working days for Business Hours, affecting how the platform calculates time on records that respect Business Hours.
Definition
Holidays is the Salesforce Setup configuration that records non-working days for Business Hours, affecting how the platform calculates time on records that respect Business Hours. Each Holiday record carries a name, a date, and an optional recurrence pattern (annually on this date). Holidays are associated with specific Business Hours configurations; the same calendar date can be a holiday in one Business Hours profile and not another, which matters for global organizations with regional Business Hours.
The configuration matters most for Case milestones, Entitlement processes, and any custom calculation that uses BusinessHours.diff() in Apex to count working time between two timestamps. Without holidays defined, the platform treats every day except weekends as a working day, which causes Service Level Agreement (SLA) calculations to count holiday days as if support were available. Service Cloud customers operating with strict SLAs need accurate Holiday configuration; without it, automated escalation paths may fire on dates when no agents are working.
How Holidays shape Business Hours math
Business Hours and Holidays together
Business Hours define the standard working hours by day of week and time zone. Holidays define exceptions to that standard. A Business Hours configuration referencing 9 AM-5 PM Monday through Friday is a standard week; with December 25 added as a holiday, that specific date is treated as non-working regardless of being a weekday. Holidays are attached to specific Business Hours records, so a Tokyo Business Hours profile can have different holidays than a New York profile.
Setup configuration
Setup > Company Settings > Holidays. The list shows all holidays defined for the org. Click New Holiday to add one: name, date, optional recurrence (annually on this date), optional time range (for partial-day holidays). After saving, associate the holiday with one or more Business Hours records through the Business Hours Holidays related list.
Recurring holidays
Annual holidays (Christmas, New Year, etc.) can be set to recur on the same date each year. The platform creates virtual instances at runtime; you do not need to add a new Holiday record per year for fixed-date holidays. For holidays that move (US Thanksgiving on the fourth Thursday of November), recurrence rules support the standard iCalendar-style patterns: nth weekday of month.
Multi-region Holiday strategy
Global organizations need a Business Hours record per region (US, EMEA, APAC) with region-specific holidays. US Memorial Day applies to US Business Hours; EU public holidays apply to EMEA Business Hours; Lunar New Year applies to APAC Business Hours. The platform supports this through the explicit Business Hours-Holiday relationship, but the configuration burden falls on the administrator: maintain region-specific holiday calendars, often pulled from authoritative regional sources annually.
Impact on Case Milestones and Entitlements
Service Cloud Entitlement processes use Business Hours to calculate milestone target times. A 24-hour first-response SLA on a Case created Friday afternoon counts 24 working hours, skipping the weekend and any defined holidays. Without Holiday configuration, an issue raised at 5 PM Friday before a long weekend would target Monday morning instead of Tuesday morning, producing missed SLAs. Holiday accuracy directly affects support team performance metrics.
Apex BusinessHours.diff()
Custom Apex calculations using BusinessHours.diff(businessHoursId, startTime, endTime) return the elapsed business hours between two times, respecting the holidays attached to the specified Business Hours. The method is the canonical way to calculate "how long was this Case open during business hours" or similar SLA-style metrics. Without holidays configured, the method overstates working time across long weekends and seasonal closures.
Maintaining the holiday calendar
Holidays need annual maintenance. Variable-date holidays (Easter, Thanksgiving, Lunar New Year) require new entries each year unless recurrence rules cover them. Government-declared holidays (one-time observances after national events) require ad-hoc additions. Set a calendar reminder in Q4 to refresh the next year's holiday list; an outdated holiday list silently produces SLA calculation errors all year.
Set up and maintain the holiday calendar
Setting up the org's holiday calendar is the annual responsibility of the Service Cloud admin or business operations team. The steps below cover the initial setup and the maintenance cycle.
- Identify the Business Hours records
Setup > Business Hours. List the active Business Hours records. Each is a target for holiday attachment.
- Source the holiday calendars
For each region's Business Hours, gather the holiday list from an authoritative source (government website, HR policy doc, regional office calendar).
- Create Holiday records
Setup > Holidays > New Holiday. Add each holiday with name, date, recurrence (if annual). For multi-region orgs, create distinct Holiday records per region or one shared Holiday per date with multiple Business Hours attachments.
- Attach holidays to Business Hours
From each Business Hours detail page, use the Holidays related list to add the relevant holidays. The same Holiday can attach to multiple Business Hours records.
- Verify with BusinessHours.diff()
Run an Apex anonymous block calling BusinessHours.diff() across a holiday range. Confirm the returned working time excludes the holiday.
- Test Case Milestone behavior
Create a test Case with an Entitlement applied. Confirm the milestone target time respects the holiday. Adjust if behavior is unexpected.
- Schedule annual refresh
Add a Q4 calendar reminder to update the holiday list for the next year. Variable-date holidays and one-off observances need new entries.
Specific date like December 25. Use recurrence to repeat annually without new records each year.
Date changes each year (Easter, Thanksgiving). Configure as a recurring rule with the appropriate weekday-of-month pattern.
Partial-day observance (Christmas Eve closing at noon). Configure with specific time range rather than full date.
Holiday attaches only to relevant Business Hours record. Lunar New Year applies to APAC; Memorial Day applies to US.
Same calendar date observed in multiple regions. One Holiday record attached to multiple Business Hours.
- Holidays are attached per Business Hours, not global. Forgetting to attach a Holiday to a regional Business Hours leaves that region treating the day as working.
- Annual maintenance is required for variable-date holidays. Without it, the calendar drifts and SLAs miscalculate silently.
- Recurrence rules support standard patterns but not all corner cases. For complex movable holidays (Easter is computed differently each year), one-off Holiday records may be easier.
- Changes to Holiday configuration do not retroactively recalculate historical Case milestones. The change applies to new Cases and milestones created after the change.
- BusinessHours.diff() in Apex respects only the Business Hours you pass. Code that hard-codes a default Business Hours Id may apply the wrong holiday calendar for a regional Case.
About the Author
Dipojjal Chakrabarti is a B2C Solution Architect with 29 Salesforce certifications and over 13 years in the Salesforce ecosystem. He runs salesforcedictionary.com to help admins, developers, architects, and cert/interview candidates sharpen their fundamentals. More about Dipojjal.
Test your knowledge
Q1. In which area of Salesforce would you typically find Holidays?
Q2. Why is understanding Holidays important for Salesforce admins?
Q3. What is the primary benefit of Holidays for Salesforce administrators?
Discussion
Loading discussion…