DEV Community

alex
alex

Posted on

How to Calculate Business Days in China (调休 Explained) — Without Losing Your Mind

#webdev #programming #software #softwareengineering

How to Calculate Business Days in China (调休 Explained) — Without Losing Your Mind

If you've ever built software that touches China — payroll, invoicing, delivery estimates, SLA timers, interest calculations — you've probably hit this problem:

China moves workdays to weekends.

And almost every holiday API gets this wrong.

The 调休 Problem

Let me show you a real example. Here's February 2026 in China:

  • Feb 14 is a Saturday. A normal calendar says: weekend.
  • The Chinese government says: it's a workday.

Why? Spring Festival 2026 runs Feb 15–23 (9 days off). To "pay back" those extra days, the State Council schedules make-up workdays (调休补班) on surrounding weekends — Feb 14 being one of them.

This isn't an edge case. In 2026, there are 6 such days. Every year has 4–8 of them.

What this breaks

Task Naive calculation Reality
Payroll for Feb 2026 20 workdays 16 workdays
"Invoice due in 3 business days" from Sep 30 Oct 10 is a Saturday → due Oct 13 Due Oct 10 (it's a make-up workday)
Interest accrual for 2026 ~261 days 248 days

If you compute any of these wrong, you either underpay staff, miss contractual deadlines, or misbill customers.

Why Most APIs Get This Wrong

I checked the major holiday APIs while building Global Holidays & Business Days API. Almost all of them — including the big names — return Chinese holidays but treat every Saturday/Sunday as a non-workday. The make-up workdays simply don't exist in their data.

Why? Because the data source most of them use (open-source holiday libraries) encodes holidays — but 调休 make-up days aren't holidays. They're the opposite: workdays disguised as weekends. They only exist in the State Council's annual notice (国务院办公厅通知), published every November.

The Fix

This is exactly why I built the Business Days API — it layers the official State Council data on top of 500+ countries of holiday data. Every workday-related endpoint applies the full 调休 logic automatically.

Example 1: Count business days in a date range 

curl "https://lingcode.me/business-days-between/CN?start=2026-01-01&end=2026-12-31"
Enter fullscreen mode Exit fullscreen mode 
{
  "calendar_days": 365,
  "business_days": 248,
  "holidays": 33,
  "weekends": 84,
  "adjusted_workdays_included": 6,
  "note": "含中国调休补班逻辑（国务院办公厅通知）"
}
Enter fullscreen mode Exit fullscreen mode

248 — not 261. The 6 make-up days are correctly counted as workdays, and the holidays that fall on weekdays are correctly excluded.

Example 2: The invoice due date problem

"Due in 3 business days, starting Sep 30, 2026." Golden Week starts Oct 1. Naive logic says Oct 13 (first Tuesday after the holiday + weekend). The API says:

curl "https://lingcode.me/next-business-day/CN?d=2026-09-30&offset=3"
Enter fullscreen mode Exit fullscreen mode 
{
  "from_date": "2026-09-30",
  "next_business_day": "2026-10-10",
  "weekday": "周六",
  "name": "调休补班",
  "calendar_days_taken": 10
}
Enter fullscreen mode Exit fullscreen mode

Oct 10 — a Saturday that is actually a workday. The API even tells you why (name: 调休补班).

Example 3: Monthly payroll report 

curl "https://lingcode.me/business-days-in-month/CN/2026/2"
Enter fullscreen mode Exit fullscreen mode 
{
  "business_days": 16,
  "holidays": 9,
  "weekends": 3,
  "adjusted_workdays_included": 2,
  "business_day_list": ["2026-02-02", "...", "2026-02-14", "..."]
}
Enter fullscreen mode Exit fullscreen mode

A full workday date list for HR systems — note Feb 14 in there.

It's Not Just China

The same API covers 500+ countries with state/province-level subdivisions (US: 57 subdivisions). So your business-days-between for US correctly handles Thanksgiving, JP handles Golden Week, DE handles Unity Day — all with the same interface:

curl "https://lingcode.me/business-days-between/US?start=2026-11-20&end=2026-12-31"
# → business_days: 27 (correctly skips Thanksgiving + Christmas)
Enter fullscreen mode Exit fullscreen mode

Use Cases Where This Matters

  1. Payroll & contractors — Chinese staff work (and get paid for) make-up Saturdays
  2. Invoicing & billing — due dates that legally roll past holidays
  3. Delivery SLAs — logistics timelines across Golden Week
  4. Interest calculation — day-count conventions for loans involving Chinese entities
  5. Project management — realistic sprint planning with Chinese teams

Try It

The 2026 dataset is complete. The 2027 dataset ships within 24 hours of the State Council's announcement (expected November 2026).

Found this useful? The API also does is-workday checks, next-holiday lookups, and full date-range analysis — all with the same 调休-aware logic. Feedback welcome via the feedback form.

Top comments (0)