Skip to main content
Employees are entitled to receive a minimum vacation pay of either four percent or six percent of their gross wages earned during the 12-month vacation entitlement year or stub period, excluding any previously paid vacation pay. This ensures compliance with employment standards legislation and guarantees fair compensation for accrued vacation time. You can configure the vacation pay percentage and accrual settings per Work Assignment.

​
Setting Vacation Pay Percentage

To set the vacation pay percentage for a Work Assignment, you can use the vacation_pay_settings endpoint. This entity will allow you to set the percentage, method of vacation pay, and the effective dates for a specific Work Assignment.
  • Each Work Assignment may have only one active Vacation Pay Setting at a time.
  • The previously active setting must be ended before creating a new one.
  • Once a setting has been used to calculate vacation pay, it cannot be deleted.
  • The API provides the earliest_valid_effective_to attribute to simplify setting the effective_to date.
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/vacation_pay_settings \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
           "work_assignment_id": <nmbr_ulid>,
           "percentage": 4,
           "effective_from": "2026-01-01",
           "vacation_pay_method": "manual"
        }'
Once the vacation pay percentage is set, all applicable Earning, Allowance, and Reimbursement Line Items for that Work Assignment will being accruing vacation pay. The accrual can be seen on the Line Item in the accrued_vacation_pay attribute. Vacation Pay is accrued on a Line Item if that Earning, Allowance, or Reimbursement Type has vacation applied in the current Province of Employment of the Work Assignment. Nmbr follows the applicable employment standards to determine if vacation pay should be accrued.

​
Paying Out Vacation Pay

Accrued vacation pay can be paid out two different ways, manual or per_period. The default method is manual, if one is not specified.

​
Manual Vacation Pay

To pay earned vacation pay manually at a time of your choosing, you can select the Vacation Pay earning type when generating a new earning. You should also include the number of hours taken to ensure reporting and records of employment are accurate. 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/earning_line_items \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
          "pay_stub_id": "axzjqzC5oOZ51h3mqmXK",
          "earning_type": "vacation_pay",
          "custom_amount" : 4.00,
          "hours": 1
        }'

​
Per-Period Vacation Pay

If you prefer that Vacation Pay is paid out automatically for each pay period, you can do so by setting the vacation pay method to per_period when creating the Vacation Pay Setting. The generated vacation pay items can be reviewed and modified before running payroll. Employees’ total vacation pay accrual as well as vacation pay that has been paid out in a given period will be displayed on their pay stubs.

​
Vacation Pay Setting Selection

The Nmbr payroll engine needs to pick one Vacation Pay Setting to apply to each Payroll. Each Vacation Pay Setting has an effective date range (effective_from to effective_to). The Nmbr payroll engine uses the vacation_pay_formula_setting attribute on the Business Entity to decide which of the Payroll’s dates must fall in the Vacation Pay Settings’ effective date ranges in order to select that Vacation Pay Setting for the Payroll:
  • pay_date (default) - select the Vacation Pay Setting whose effective range contains the Payroll’s pay_date.
  • period_start - select the Vacation Pay Setting whose effective range contains the Payroll’s period_start.
  • period_end - select the Vacation Pay Setting whose effective range contains the Payroll’s period_end.

​
Example

A Work Assignment has two Vacation Pay Settings:
Settingeffective_fromeffective_to
Setting A (4%)2026-01-012026-06-30
Setting B (6%)2026-07-01(open)
A Payroll has period_start = 2026-06-20, period_end = 2026-07-03, and pay_date = 2026-07-10. The selected setting depends on the Business Entity’s vacation_pay_formula_setting:
  • pay_date: Setting B will be used, because the Payroll’s pay_date (2026-07-10) falls in B’s range
  • period_start: Setting A will be used, because the Payroll’s period_start (2026-06-20) falls in A’s range
  • period_end: Setting B will be used, because the Payroll’s period_end (2026-07-03) falls in B’s range