Skip to main content
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. 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 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 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.
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.
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:
Example 4: Enable statutory holiday pay using Ontario’s rules for calculating statutory holiday pay, calculating the entitlement amount:
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):
Example 6: Pay a fixed 8 hours of statutory holiday pay at the work assignment’s highest-rate pay rate, regardless of provincial rules:
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):
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:

​
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.