Quick: how many business days are in March 2026?
If you answered 22, you skipped weekends but forgot that different countries have different holidays in March. The US doesn't have a federal holiday in March, so 22 is correct there. But India celebrates Holi. Mexico has Benito Juárez's birthday. Japan has Vernal Equinox Day.
The correct answer depends entirely on where your users are. And that's just the beginning of why business day calculations are more complex than they appear.
The Weekend Problem
"Weekdays are Monday through Friday" is a reasonable assumption if your entire user base is in the Western world. It's wrong for about two billion people.
In many Middle Eastern countries, the traditional work week runs Sunday through Thursday. Friday and Saturday are the weekend. In some countries, the weekend is Friday and Saturday. Others use Saturday and Sunday. A few have only a single-day weekend.
Saudi Arabia, the UAE, and several other Gulf states recently shifted to a Saturday-Sunday weekend to align with global financial markets. But the transition wasn't instantaneous—some sectors still observe different schedules. Building "weekend" logic as a hardcoded Saturday-Sunday check will produce wrong results for a meaningful portion of the global workforce.
The pattern here is the same one that plagues all internationalization: assumptions that feel universal but aren't.
Holidays Break Everything
Even once you've sorted out weekends, holidays introduce a whole new layer of complexity.
National holidays vary by country—obviously. Less obviously, they vary by region within countries. The US has federal holidays, but individual states have additional ones. Germany's holidays differ by Bundesland. Canada's provinces don't all observe the same holidays.
Some holidays move. Easter is the most famous moveable holiday, but plenty of others shift year to year. Holidays based on lunar calendars (Eid, Chinese New Year, Diwali) fall on different Gregorian calendar dates each year. A holiday calculator that works for 2026 might be wrong for 2027.
Some holidays have substitute rules. In Japan, if a national holiday falls on a Sunday, the following Monday becomes a holiday. In the UK, bank holidays falling on weekends are "moved" to the next working day. These substitution rules differ by country.
And then there are the one-time holidays. Royal funerals, national celebrations, election days. These can be declared with short notice, and no algorithm can predict them. The UK had a one-off bank holiday for the Queen's funeral in 2022. Japan had extra holidays for the Emperor's enthronement in 2019.
Any system that calculates business days needs a holiday database that's actively maintained—not a formula.
Why This Matters in Software
Business day calculations aren't academic. They affect real money and real deadlines.
SLA commitments are measured in business days. "We'll respond within 2 business days" means something very different if you count holidays versus if you don't. A support ticket filed on Wednesday before a three-day weekend might not be due until the following Tuesday—but only if your system knows about the holiday.
Payment terms like "Net 30" sometimes mean 30 business days, sometimes 30 calendar days. The distinction matters for cash flow management. A vendor expecting payment in 30 business days is actually giving you about six weeks of calendar time.
Shipping estimates that say "3-5 business days" need to exclude weekends and holidays. A package shipped on the Friday before a Monday holiday doesn't arrive until at least Thursday—five calendar days but only three business days in transit.
Financial settlement follows strict business day rules. Stock trades settle on T+1 (one business day after the trade). Bond settlements are T+2. Getting these wrong has regulatory and financial consequences.
HR and payroll systems calculate everything from PTO accrual to payroll dates based on working days. A payroll that runs on the "last business day of the month" needs to know when that actually is.
The Cross-Border Headache
This is where most teams throw up their hands.
Consider a contract between a US company and a German supplier. The contract says "delivery within 10 business days." Whose business days? The US celebrates Independence Day on July 4th. Germany doesn't. Germany celebrates Tag der Deutschen Einheit on October 3rd. The US doesn't.
International businesses generally specify which country's calendar governs. But if your application calculates deadlines automatically, it needs to know which calendar to use for each transaction. A single "business days" calculation might need different holiday calendars depending on which parties are involved.
Payment processing across borders faces this constantly. A wire transfer between New York and London might be delayed by a US holiday that the UK doesn't observe, or vice versa. Both banking systems need to be open for the transfer to process. Miss this, and money sits in limbo while everyone points fingers at the other side.
The API Approach
Maintaining your own holiday database is possible but tedious. Holidays change. Countries add holidays, remove them, or change the dates. Regional variations multiply the complexity.
An API handles this by maintaining the data externally:
const response = await fetch(
'https://api.apiverve.com/v1/workingdays?country=US&year=2026&month=3',
{ headers: { 'x-api-key': 'YOUR_API_KEY' } }
);
const { data } = await response.json();
// data.workingDaysCount → 22
// data.nonWorkingDays → [{ date: "2026-03-01", reasons: ["weekend"] }, ...]
// Each non-working day includes the reason: "weekend" or the holiday name
The response tells you not just the count but the specific dates and reasons. A weekend is different from a holiday in some business contexts—some contracts count weekends but not holidays, or vice versa.
Common Mistakes
Hardcoding holidays. Every developer thinks this will be fine. It never stays fine. A list of holidays that was correct when written becomes wrong within a year. If you must maintain a local list, treat it as data that requires annual updates, not code.
Ignoring regional holidays. National holidays are the minimum. If your users are in Bavaria, Bavarian holidays matter. If they're in Quebec, Quebec holidays matter. The difference can be several days per year.
Assuming "business day" means the same thing everywhere. It doesn't. In some industries and countries, Saturday is a half working day. Some count it as a full working day. Banking, retail, and government often have different definitions even within the same country.
Forgetting timezone boundaries. When it's already Friday in Tokyo, it's still Thursday in New York. If your deadline is "5 business days from today," the definition of "today" depends on where the user is.
Not handling the "next business day" edge case. What's the next business day after December 31st? Good luck. It depends on the year and country. Some countries have holidays on January 2nd. Some have extended New Year breaks. The answer might be January 3rd, 4th, or even later.
How Much Precision Do You Need?
Not every application needs per-country holiday awareness. A project management tool where all users are in one country can use that country's calendar and be fine. A personal todo app might not need business day calculations at all.
But any application that deals with contractual deadlines, financial settlements, international operations, or SLA tracking needs proper business day logic. The cost of getting it wrong—missed deadlines, SLA violations, incorrect payment dates—exceeds the cost of implementing it right.
Start with weekends. Add national holidays for your primary country. Then expand to regional holidays and additional countries as your user base grows. Each layer adds accuracy, and the API approach means you don't have to maintain the data yourself.
Calculate working days accurately with the Working Days API. Look up holidays worldwide with the World Holidays API. Get date math right the first time with the Date Calculator API.
Originally published at APIVerve Blog
Top comments (0)