---
title: "Explain statutory holiday pay calculation"
method: POST
path: "/calculations/statutory_holiday_pay"
tags: ["Calculations"]
---

# Explain statutory holiday pay calculation

`POST /calculations/statutory_holiday_pay`

Explain how statutory holiday pay would be calculated for the pay stub's work assignment, optionally overriding which dates are treated as holidays and/or the statutory holiday pay configuration. With no overrides, behaves as a pure explanation of how statutory holiday pay was or will be calculated under the work assignment's current configuration.

## Request body

- object
  - `pay_stub_id` string, required — The pay stub to explain statutory holiday pay for.
  - `holiday_dates` string[] — Optional array of `Y-m-d` dates within the pay stub's pay period to treat as statutory holidays. When omitted, the statutory holidays for the work assignment's Province of Work (POW) are used.
  - `configuration` object — Optional override of the work assignment's statutory holiday pay configuration. When omitted, the work assignment's `ca_statutory_holiday_pay` tax property in effect at the start of the pay period is used.
    - `calculate_entitlement` boolean
    - `calculation_strategy` 'hours_only' | 'provincial_rules_only' | 'provincial_rules_or_hours'
    - `override_rule_set` 'AB' | 'BC' | 'FEDERAL' | 'MB' | 'NB' | 'NL' | 'NS' | 'NT' | 'NU' | 'OC' | 'ON' | 'PE' | 'QC' | 'SK' | 'YT'
    - `override_date_basis` 'before_holiday_day' | 'before_holiday_pay_period' | 'before_holiday_week'
    - `hours` number
    - `pay_rate` 'earliest_effective_from' | 'highest_expected_hours_per_week' | 'highest_expected_weekly_amount' | 'highest_rate' | 'latest_effective_from'

## Response `200`

OK

- object
  - `id` string — The unique identifier of the object in Nmbr.
  - `object` string — The type of the object in Nmbr (`"statutory_holiday_pay_explanation"`).
  - `data` StatutoryHolidayPayExplanation
    - `not_applicable_reason` unknown
    - `jurisdiction` string, nullable — The effective Province of Work (work assignment's POW with any `override_rule_set` applied) used to look up holidays and provincial rules, in `ca_xx` format (one of `ca_ab`, `ca_bc`, `ca_mb`, `ca_nb`, `ca_nl`, `ca_ns`, `ca_nt`, `ca_nu`, `ca_on`, `ca_pe`, `ca_qc`, `ca_sk`, `ca_yt`, or `ca_federal`). `null` when no Province of Work could be resolved.
    - `configuration` object, nullable — The Statutory Holiday Pay tax property configuration on the work assignment as of the start of the pay period, or the configuration override supplied in the request body. `null` when neither is present.
      - `calculate_entitlement` boolean
      - `calculation_strategy` string, nullable
      - `override_rule_set` unknown
      - `override_date_basis` unknown
      - `hours` unknown
      - `pay_rate` unknown
    - `default_rules` object[], nullable — The rules defined by the work assignment's own Province of Work (ignoring any `override_rule_set`). Describes what would apply by default.
      - `id` string, nullable — The rule's stable identifier (e.g. `regular_earnings`, `commission`). Used to cross-reference per-holiday calculations under `holidays[].entitlement.provincial_rules_calculation[].id`.
      - `name` string, nullable — The translated human-readable name of the rule for the request locale.
      - `explanation` string, nullable — A prose sentence describing how this rule computes the entitlement (e.g. "The last 4 weeks of eligible earnings, ending the day before the holiday week begins, divided by 20.").
      - `earning_date_basis` string, nullable — Which calendar boundary the rule's look-back window ends on. One of `before_holiday_day`, `before_holiday_week`, or `before_holiday_pay_period`.
      - `eligible_days_in_range` number, nullable — The width of the look-back window in calendar days (e.g. 28 for Ontario's 4-week window).
      - `eligible_work_days_in_range` number, nullable — The divisor used to convert the window's effective earnings into a per-holiday entitlement (e.g. 20 for Ontario).
      - `eligible_earning_types` object[], nullable — Earning types that count toward this rule's look-back sum. Earnings of types not listed here are excluded.
        - `id` string, nullable
        - `object` string, nullable
        - `data` object, nullable
          - `type` string, nullable
          - `label` string, nullable
          - `supported_payroll_types` object, nullable
            - `regular` boolean
            - `historical` boolean
            - `off_cycle` boolean
        - `links` object, nullable
          - `self` string, nullable
      - `eligible_allowance_types` object, nullable — Allowance types that count toward this rule's look-back sum. Usually empty.
      - `eligible_reimbursement_types` object, nullable — Reimbursement types that count toward this rule's look-back sum. Usually empty.
    - `overridden_rules` unknown
    - `holidays` object[], nullable — One entry per statutory holiday observed in the pay period (or per `holiday_dates` entry when an override was supplied in the request).
      - `holiday` object, nullable — The Holiday record being calculated against. `id` and timestamps are `null` for hypothetical holidays supplied via `holiday_dates`.
        - `id` string, nullable
        - `object` string, nullable
        - `data` object, nullable
          - `jurisdiction` string, nullable
          - `type` string, nullable
          - `name` string, nullable
          - `name_translations` object, nullable
            - `en` string, nullable
            - `fr` string, nullable
          - `name_translated` string — The translation of the `name` property for the request locale. Computed using the values in `name` and `name_translations` and the value of the request's `Accept-Language` header.
          - `original_date` string, nullable
          - `observed_date` string, nullable
          - `created_at` string, nullable
          - `updated_at` string, nullable
        - `links` object, nullable
          - `self` string, nullable
      - `line_item_id` unknown
      - `amount` number, nullable — The dollar amount this pay stub allocates for the holiday: `gross_amount` less `already_allocated.amount`, floored at `0`. `0` when entitlement isn't being calculated (see `not_applicable_reason`).
      - `hours` number, nullable — The hours that form the basis of `amount`, on the same basis as the amount. `0` when entitlement isn't being calculated.
      - `gross_amount` number, nullable — The full dollar entitlement the employee is owed for this holiday, after applying the configuration's strategy and before netting off any statutory holiday pay already allocated on another pay stub. Equal to `amount` unless `already_allocated` is present.
      - `gross_hours` number, nullable — The hours that form the basis of `gross_amount`.
      - `already_allocated` unknown
      - `entitlement` object, nullable — The breakdown of how `amount` and `hours` were computed. `null` when entitlement isn't being calculated for this pay stub.
        - `fixed_hours_calculation` unknown
        - `provincial_rules_calculation` object[], nullable — Per-rule results from the provincial calculator. Always populated under `provincial_rules_only` and `provincial_rules_or_hours`; `null` under `hours_only`. Most provinces have a single `regular_earnings` rule; Quebec splits earnings and commissions into separate rules.
          - `id` string, nullable — The rule's identifier (e.g. `regular_earnings`). Matches an entry in `default_rules` / `overridden_rules`.
          - `amount` number, nullable — The entitlement this rule contributes to the holiday, computed as `totals.effective_amount ÷ eligible_work_days_in_range`.
          - `hours` number, nullable — The hours basis for this rule's contribution, on the same basis as `amount`.
          - `eligible_date_range` object, nullable — The look-back window for this rule, derived from the rule's `earning_date_basis` and `eligible_days_in_range`. Inclusive on both ends.
            - `start` string, nullable
            - `end` string, nullable
          - `totals` object, nullable — Aggregated totals across every pay period that overlapped the look-back window, before dividing by the rule's `eligible_work_days_in_range`. `dated_*` fields sum line items whose `earned_on` date falls inside the window (included at 100%); `undated_*` fields sum line items without an `earned_on` (prorated by each pay period's coverage ratio); `effective_*` is `dated_*` plus `undated_*_prorated`.
            - `dated_amount` number, nullable
            - `dated_hours` number, nullable
            - `undated_amount` number, nullable
            - `undated_hours` number, nullable
            - `undated_amount_prorated` number, nullable — `undated_amount` after applying each pay period's `undated_coverage_ratio`. This is the value that contributes to `effective_amount`.
            - `undated_hours_prorated` number, nullable — `undated_hours` after applying each pay period's `undated_coverage_ratio`.
            - `effective_amount` number, nullable — The numerator divided by `eligible_work_days_in_range` to produce the per-holiday `amount`. Equal to `dated_amount + undated_amount_prorated`.
            - `effective_hours` number, nullable — The numerator divided by `eligible_work_days_in_range` to produce the per-holiday `hours`. Equal to `dated_hours + undated_hours_prorated`.
          - `payroll_summaries` object[], nullable — The per-payroll breakdown that produced `totals`. Each entry covers one paid prior payroll (or the current draft payroll) whose pay period overlapped the look-back window.
            - `payroll` object, nullable — The Payroll being summarized.
              - …
            - `pay_period` object, nullable — The pay period start/end dates for this payroll. Both inclusive.
              - …
            - `dated_amount_total` number, nullable
            - `dated_hours_total` number, nullable
            - `undated_amount_total` number, nullable
            - `undated_hours_total` number, nullable
            - `eligible_days_in_pay_period` number, nullable — The number of calendar days from this pay period that fall inside the rule's `eligible_date_range`. The numerator of `undated_coverage_ratio`.
            - `days_in_pay_period` number, nullable — The total number of calendar days in this pay period. The denominator of `undated_coverage_ratio`.
            - `undated_coverage_ratio` number, nullable — The fraction of this pay period that overlaps the rule's `eligible_date_range`. Used to prorate the period's undated line items into the look-back sum.
            - `undated_amount_prorated` number, nullable
            - `undated_hours_prorated` number, nullable
            - `effective_amount` number, nullable
            - `effective_hours` number, nullable
            - `earlier_holidays_amount` number, nullable — For cascading provincial rules (e.g. Ontario, where Statutory Holiday Pay itself counts as eligible earnings), the sum of entitlements computed for earlier holidays in the current pay period that fall inside this rule's eligible date range. Always `0` for prior payrolls' summaries. Treated as additional dated earnings.
            - `earlier_holidays_hours` number, nullable — The hours equivalent of `earlier_holidays_amount`.
            - `dated_line_items` object, nullable — The line items from this pay period's pay stub that have an `earned_on` date. Each entry's `in_range` flag indicates whether the `earned_on` falls inside the rule's `eligible_date_range` and therefore counted toward `dated_amount` / `dated_hours`.
            - `undated_line_items` object[], nullable — The line items from this pay period's pay stub that have no `earned_on` date — they're assumed to be spread evenly across the period and contribute to `undated_amount` / `undated_hours` after proration by `undated_coverage_ratio`.
              - …
        - `chosen_method` string, nullable — Which calculator produced the chosen amount. Either `provincial_rules` or `fixed_hours`. Under `provincial_rules_or_hours` this can differ per holiday — the engine picks whichever yields the larger entitlement.

---

[API](https://skmtc.net/nmbr/apis/nmbr-api.md) · [All operations](https://skmtc.net/nmbr/apis/nmbr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nmbr/nmbr-api/revisions/c2532d856ea2/schema)