> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nmbr.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Statutory Holiday Pay

> Set up and calculate statutory holiday pay

In Canada, employers may be required to pay employees for statutory holidays. The amounts paid are calculated based on the employee's earnings in a period leading up to the holiday. Each province and territory has its own rules for calculating statutory holiday pay, including:

* Which holidays are statutory holidays and when they are observed. For example, Boxing Day is a statutory holiday in Ontario but not Alberta.

* How many days or weeks of earnings to include when calculating statutory holiday pay. For example, British Columbia considers 30 days of earnings, Yukon considers 2 weeks of earnings, Quebec considers 4 weeks of regular earnings and 12 weeks of commission, etc.

* Which earning types are included in the statutory holiday pay calculation. For example, not all provinces include bonuses.

## Enabling Statutory Holiday Pay

To enable statutory holiday pay, you must create a `ca::statutory_holiday_pay` tax-property for each work-assignment using the [`tax_properties` API](/guides/payroll-fundamentals/tax-properties).

The `value` of the tax-property is an object that may include any of the following optional properties:

* `calculate_entitlement` (boolean, optional) - Whether to calculate the entitlement amount (`true`) or default to a \$0 amount that can be overridden by the end user (`false`). Defaults to `false`.

* `calculation_strategy` (enum, optional) - Which strategy to use for calculating the entitlement amount. Defaults to `provincial_rules_only`. Must be one of:
  * `provincial_rules_only`: Calculate the entitlement amount using the work assignment's Province of Work (POW)'s rules. See [Provincial Rules Calculations](#provincial-rules-calculations) below.

  * `hours_only`: Calculate the entitlement amount as a fixed number of hours at one of the work assignment's hourly pay rates. See [Fixed Hours Calculations](#fixed-hours-calculations) below.

  * `provincial_rules_or_hours`: Calculate the entitlement amount using both strategies and use whichever amount is greater. This lets the employer guarantee the employee a minimum number of paid hours per holiday while still paying out more when provincial rules require it (for example, when commissions push the provincial amount above the minimum).

### Provincial Rules Properties

The following properties are allowed only when `calculation_strategy` is `provincial_rules_only` (the default) or `provincial_rules_or_hours`. Sending them when `calculation_strategy` is `hours_only` returns a validation error.

* `override_rule_set` (string, optional) - Override the work assignment's Province of Work and use a different province or territory's rules for statutory holiday pay.

* `override_date_basis` (enum, optional) - Override the selected province or territory's date basis for calculating statutory holiday pay. Must be one of:
  * `before_holiday_day`: Calculates statutory holiday pay based on included earnings over a period ending the day before the holiday is observed.

  * `before_holiday_week`: Calculates statutory holiday pay based on included earnings over a period ending the day before the holiday week begins. The beginning of the holiday week isn't necessarily the beginning of the calendar week the holiday is in. Nmbr calculates the beginning of the holiday week by taking the pay period start date and adding whole weeks until the date is less than a week before the holiday. This helps reduce proration (see below) for provinces that look at earnings over a period of weeks rather than days.

  * `before_holiday_pay_period`: Calculates statutory holiday pay based on included earnings over a period ending the day before the holiday pay period begins.

### Fixed Hours Properties

The following properties are required when `calculation_strategy` is `hours_only` or `provincial_rules_or_hours`. Sending them under any other strategy (including the default `provincial_rules_only`) returns a validation error.

* `hours` (number, required) - The number of hours to pay the employee for each statutory holiday. Must be between 0 and 40.

* `pay_rate` (enum, required) - Which of the work assignment's hourly pay rates to use when calculating the fixed-hours amount. A work assignment may have multiple hourly pay rates effective on the holiday's observed date, so this selector specifies how to pick one. Must be one of:

  * `highest_rate`: The pay rate with the highest hourly `rate`.

  * `highest_expected_hours_per_week`: The pay rate with the highest `expected_hours_per_week`.

  * `highest_expected_weekly_amount`: The pay rate with the highest expected weekly amount (`rate` × `expected_hours_per_week`).

  * `earliest_effective_from`: The pay rate with the earliest `effective_from` date.

  * `latest_effective_from`: The pay rate with the latest `effective_from` date.

  Ties are broken by the highest `rate`, then the earliest `effective_from` date, then the earliest `id`. If the work assignment has no hourly pay rate effective on the holiday's observed date, the fixed-hours amount is \$0.

### Examples

**Example 1:** Enable statutory holiday pay using the work assignment's Province of Work's rules for calculating statutory holiday pay, defaulting to a \$0 amount.

```
  "value": {}
```

**Example 2:** Enable statutory holiday pay using the work assignment's Province of Work's rules for calculating statutory holiday pay, calculating the entitlement amount.

```
  "value": {
    "calculate_entitlement": true
  }
```

**Example 3:** Enable statutory holiday pay using the work assignment's Province of Work's rules for calculating statutory holiday pay, calculating the entitlement amount, but calculating it based on included earnings over a period ending the day before the holiday pay period begins instead of the default date basis for the province/territory:

```
  "value": {
    "calculate_entitlement": true,
    "override_date_basis": "before_holiday_pay_period"
  }
```

**Example 4:** Enable statutory holiday pay using Ontario's rules for calculating statutory holiday pay, calculating the entitlement amount:

```
  "value": {
    "calculate_entitlement": true,
    "override_rule_set": "ON"
  }
```

**Example 5:** Enable statutory holiday pay using Ontario's rules for calculating statutory holiday pay, calculating the entitlement amount, but calculating it based on included earnings over a period ending the day before the holiday *pay period* begins instead of the day before the holiday *week* begins (the default date basis for Ontario):

```
  "value": {
    "calculate_entitlement": true,
    "override_rule_set": "ON",
    "override_date_basis": "before_holiday_pay_period"
  }
```

**Example 6:** Pay a fixed 8 hours of statutory holiday pay at the work assignment's highest-rate pay rate, regardless of provincial rules:

```
  "value": {
    "calculate_entitlement": true,
    "calculation_strategy": "hours_only",
    "hours": 8,
    "pay_rate": "highest_rate"
  }
```

**Example 7:** Guarantee the employee at least 8 hours of statutory holiday pay at their highest-rate pay rate, but pay more if the work assignment's Province of Work's rules calculate a greater amount (for example, when commissions are included):

```
  "value": {
    "calculate_entitlement": true,
    "calculation_strategy": "provincial_rules_or_hours",
    "hours": 8,
    "pay_rate": "highest_rate"
  }
```

Statutory holiday pay will not be calculated for any work-assignment unless a valid tax-property is configured.

## Fixed Hours Calculations

When `calculation_strategy` is `hours_only` or `provincial_rules_or_hours`, Nmbr calculates a fixed-hours amount equal to `hours` × the rate of the hourly pay rate selected by `pay_rate`. The pay rate is resolved against the work assignment's hourly pay rates that are effective on the holiday's observed date. If no hourly pay rate is effective on that date, the fixed-hours amount is \$0.

For `provincial_rules_or_hours`, Nmbr calculates both the provincial amount and the fixed-hours amount and uses whichever is greater.

## Provincial Rules Calculations

Nmbr supports statutory holiday pay calculations for every province and territory. When `calculation_strategy` is `provincial_rules_only` or `provincial_rules_or_hours`, entitlement amounts under provincial rules are calculated as follows:

| Province or Territory     | Rule             | Entitlement Amount Calculation                                                                                                | Included Earning Types                                                                                                                                                                                                                                                                                                        |
| ------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alberta                   | Regular earnings | The last 4 weeks of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 20    | - Wage<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Bonus (Non-Discretionary)                                                                                                                                                                                                              |
| British Columbia          | Regular earnings | The last 30 days of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 21.42 | - Wage<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Bonus (Non-Discretionary)<br />- Vacation Pay<br />- Vacation Pay (Employee Terminated)<br />- Vacation Pay (Time Taken)<br />- Vacation Pay (No Time Taken)<br />- Statutory Holiday Pay                                              |
| Manitoba                  | Regular earnings | The last 4 weeks of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 20    | - Wage<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Bonus (Non-Discretionary)<br />- Vacation Pay<br />- Vacation Pay (Employee Terminated)<br />- Vacation Pay (Time Taken)<br />- Vacation Pay (No Time Taken)<br />- Statutory Holiday Pay                                              |
| New Brunswick             | Regular earnings | The last 30 days of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 21.42 | - Wage<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Bonus (Non-Discretionary)                                                                                                                                                                                                              |
| Newfoundland and Labrador | Regular earnings | The last 3 weeks of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 15    | - Wage<br />- Overtime<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Bonus (Discretionary)<br />- Bonus (Non-Discretionary)<br />- Vacation Pay<br />- Vacation Pay (Employee Terminated)<br />- Vacation Pay (Time Taken)<br />- Vacation Pay (No Time Taken)<br />- Statutory Holiday Pay |
| Nova Scotia               | Regular earnings | The last 30 days of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 21.42 | - Wage<br />- Overtime<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Bonus (Non-Discretionary)<br />- Statutory Holiday Pay                                                                                                                                                                 |
| Northwest Territories     | Regular earnings | The last 4 weeks of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 20    | - Wage<br />- Overtime<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Vacation Pay<br />- Vacation Pay (Employee Terminated)<br />- Vacation Pay (Time Taken)<br />- Vacation Pay (No Time Taken)<br />- Statutory Holiday Pay                                                               |
| Nunavut                   | Regular earnings | The last 4 weeks of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 20    | - Wage<br />- Overtime<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Vacation Pay<br />- Vacation Pay (Employee Terminated)<br />- Vacation Pay (Time Taken)<br />- Vacation Pay (No Time Taken)<br />- Statutory Holiday Pay                                                               |
| Ontario                   | Regular earnings | The last 4 weeks of included earnings, ending the day before the holiday week begins (`before_holiday_week`), divided by 20   | - Wage<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Bonus (Non-Discretionary)<br />- Statutory Holiday Pay                                                                                                                                                                                 |
| Prince Edward Island      | Regular earnings | The last 4 weeks of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 20    | - Wage<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Vacation Pay<br />- Vacation Pay (Employee Terminated)<br />- Vacation Pay (Time Taken)<br />- Vacation Pay (No Time Taken)<br />- Statutory Holiday Pay                                                                               |
| Quebec                    | Regular earnings | The last 4 weeks of included earnings, ending the day before the holiday week begins (`before_holiday_week`), divided by 20   | - Wage<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Gratuity<br />- Statutory Holiday Pay                                                                                                                                                                                                                    |
| Quebec                    | Commission       | The last 12 weeks of included earnings, ending the day before the holiday week begins (`before_holiday_week`), divided by 60  | - Commission                                                                                                                                                                                                                                                                                                                  |
| Saskatchewan              | Regular earnings | The last 4 weeks of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 20    | - Wage<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission<br />- Vacation Pay<br />- Vacation Pay (Employee Terminated)<br />- Vacation Pay (Time Taken)<br />- Vacation Pay (No Time Taken)<br />- Statutory Holiday Pay                                                                               |
| Yukon                     | Regular earnings | The last 2 weeks of included earnings, ending the day before the holiday is observed (`before_holiday_day`), divided by 10    | - Wage<br />- Retroactive Pay<br />- Retroactive Pay Increase<br />- Commission                                                                                                                                                                                                                                               |

## Earned-On Dates

Earning, allowance, and reimbursement line items have an optional `earned_on` date that represents the day the line item was earned on. When `earned_on` is set, Nmbr can determine precisely whether a line item falls within a holiday's lookback window. If a line item's `earned_on` date is in the window, the item's amount is included in full; if not, it is excluded entirely.

For example, in Ontario the lookback window is the 4 weeks ending the day before the holiday week begins. A bonus with an `earned_on` date inside that window contributes its full amount to the entitlement calculation. The same bonus with an `earned_on` date outside the window contributes nothing.

Each line item exposes three earned-on fields:

* `managed_earned_on` - The system-assigned earned-on date.
* `custom_earned_on` - An override you can set via the API or Portal. Must fall within the payroll's pay period.
* `earned_on` — The effective value: `custom_earned_on` if set, `managed_earned_on` otherwise. Read-only.

## Proration

When a line item has no `earned_on` date, Nmbr falls back to proration. The line item's contribution to the entitlement calculation is scaled by how much of its pay period overlaps with the lookback window.

For example, in Ontario the lookback window is the 4 weeks ending the day before the holiday week begins. Depending on the date of the holiday and the pay schedule, that window may cover 0, 1, or 2 partial pay periods. If the window covers 5 days of a 30 day pay period, undated line items from that pay period contribute 5/30ths (1/6th) of their value to the entitlement calculation.

Proration is a coarser approximation than `earned_on`-based inclusion: it assumes line items are spread evenly across the pay period, which may over- or under-count earnings that were actually concentrated at one end of the period. Setting `custom_earned_on` on line items where the precise date is known will produce more accurate entitlement amounts.

It is also sometimes possible to avoid proration for undated line items by aligning pay periods with the lookback window:

* Use a weekly or bi-weekly pay frequency.
* Set `override_rule_set` to a province or territory whose entitlement amount calculations are based on an even number of weeks.
* Set `override_date_basis` to `before_holiday_pay_period`.

This will result in the entitlement amount including earnings only from complete 1- or 2-week pay periods. However, the results may not be correct according to the work assignment's Province of Work's regulations, and the employee may be over- or under-paid what they are actually entitled.

## Statutory Holiday Pay on Statutory Holiday Pay

Some provinces and territories include statutory holiday pay for one holiday in the earnings for another holiday. For example, statutory holiday pay earned for Christmas may need to be included when calculating the entitlement amount for Boxing Day, and both may need to be included when calculating the entitlement amount for New Years Day. Nmbr accounts for this both for statutory holidays in earlier pay periods and for statutory holidays in the same pay period.

## Limitations

**Eligibility:** Each province and territory has its own rules for determining whether employees are eligible for statutory holiday pay. Nmbr does not currently calculate eligibility. If the statutory holiday pay tax property is created on a work assignment, the employee is assumed to be eligible for statutory holiday pay.

**Industry-Specific Rules:** Some provinces and territories have additional industry-specific rules for statutory holiday pay in industries such as construction. Nmbr does not currently apply these rules.