Skip to content
Calcadian logoCalcadian

Business Calendars

A Business Calendar is a saved definition of what counts as a working day for one team, country or contract.

Two ways to specify a calendar

Every business-day operation accepts either a saved calendar id or an inline specification. When business_calendar_id is supplied, all other calendar fields are ignored, so a request can never half-use a saved calendar.

json
// saved calendar
{ "start_date": "2026-03-02", "end_date": "2026-03-31",
  "business_calendar_id": "3f1d1c0e-58f3-4b7a-9d3e-2b3f9f0a1c22" }

// inline
{ "start_date": "2026-03-02", "end_date": "2026-03-31",
  "country_code": "MY", "subdivision_code": "10",
  "working_days": [1,2,3,4,5], "include_public_holidays": true }

Calendar fields

  • business_calendar_id - Id of a saved Business Calendar owned by the API key's account. When supplied, all other calendar fields are ignored. Requires the Business Calendars feature on the account.
  • country_code - Two-letter ISO 3166-1 country code used for public holidays.
  • subdivision_code - Region/state code within the country. If supplied and not supported for that country, the request fails with 422 INVALID_SUBDIVISION. There is no silent fallback to national holidays.
  • working_days - ISO weekday numbers that count as working days. 1 = Monday, 7 = Sunday. Defaults to [1,2,3,4,5].
  • include_public_holidays - Whether public holidays for the country/subdivision are treated as non-working days.

Subdivisions never fall back silently

If you send a subdivision_code that a country does not support, the request fails with 422 INVALID_SUBDIVISION. It is never quietly downgraded to national holidays, because a silently wrong holiday set produces a silently wrong contractual date.

What counts as a holiday

Only public and bank holidays are treated as non-working days. Observances, religious dates that are not public holidays and school terms are not. Anything else your organisation closes for should be added as a custom holiday on a saved calendar.

Custom holidays and excluded dates

  • Custom holiday: a recurring company closure, for example a founders' day.
  • Excluded date: a one-off non-working day, for example a site shutdown.

Both are non-working. They are separated so a calculation trace can tell you which rule removed a given day.

Determinism and attribution

Results record the holiday provider and its version, so a calculation can be reproduced and audited later. The engine itself is pure: it never fetches a provider or a database mid-calculation.

Access

Saved Business Calendars are a paid feature and are gated per account. Without it, the inline fields still work. Calendars are managed at Business Calendars. Requesting a calendar owned by another account returns 404 BUSINESS_CALENDAR_NOT_FOUND rather than confirming it exists.