Setting Vacation Pay Percentage
To set the vacation pay percentage for a Work Assignment, you can use thevacation_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_toattribute to simplify setting theeffective_todate.
accrued_vacation_pay attribute.
Vacation Pay is accrued on a Line Item if that Line Item’s 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.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 toper_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.
Using a Business Preset
Setbusiness_preset_id on the Vacation Pay Setting to create the payout line item from a Business Preset. The payout carries the preset’s title and accounting codes, and accounting code rules that target the preset apply to it.
The preset must belong to the work assignment’s business entity, have the earning type, and carry either no subtype or the vacation_pay subtype. When the preset sets no title, the payout keeps its default “Vacation Pay Out” title.
business_preset_id on the setting first.
Tag Attribution
When tags are used for accounting attribution, the automatically generated payout derives its own tag split from the remuneration that funded it, rather than inheriting the work assignment’s tag allocations, so a payout is attributed across departments in the same proportions as the pay it accrued from. See Derived tags on vacation payouts.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’spay_date.period_start- select the Vacation Pay Setting whose effective range contains the Payroll’speriod_start.period_end- select the Vacation Pay Setting whose effective range contains the Payroll’speriod_end.
Example
A Work Assignment has two Vacation Pay Settings:
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’spay_date(2026-07-10) falls in B’s rangeperiod_start: Setting A will be used, because the Payroll’speriod_start(2026-06-20) falls in A’s rangeperiod_end: Setting B will be used, because the Payroll’speriod_end(2026-07-03) falls in B’s range