Configuring Benefits

Benefits represent payroll contributions tied to employer or employee plans. These contributions may be monetary or calculated based on earnings, and may be shared between the employer and the employee. Benefits are configured using two distinct entities:

Employer Benefits: Contributions paid by the employer towards employee benefit plans.
Employee Benefits: Contributions deducted from the employees earnings to contribute to their benefits.

Both types can generate line items during payroll, which represent actual contributions applied per pay period.

Employer Contributions

Employer Benefits

Employer Benefits represent the configuration of recurring contributions made by the employer towards benefit plans, such as health insurance or retirement contributions.

Employer Benefits are contributions made by the employer towards employee benefit plans.
They can be fixed amounts, amounts per hour worked, or calculated based on employee earnings.
During the effective dates, these contributions are automatically applied to the payroll as an Employer Benefit Line Item.
Employer Benefits can be inherited from a Business Preset, allowing for consistent benefit configurations across multiple work assignments.

Field	Description
`work_assignment_id`	Required. The work assignment this benefit applies to. Must belong to a work assignment associated with an entity of type Employee.
`business_preset_id`	Optional Business Preset to inherit from.
`employer_benefit_type`	The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`). Required unless inherited from a Business Preset.
`employee_benefit_id`	Optional reference to an employee_benefit used solely for display.
`title`	Label for identifying the benefit.
`effective_from`	Start date of the Benefit.
`effective_to`	The end date for this plan (optional)
`amount`	The contribution value. Read against `amount_type`. See Amount Types.
`amount_type`	`fixed` for a dollar amount, `fixed_per_hour` for a dollar amount per hour, `percent` for a percentage of income. Defaults to `fixed`.
`percent`	Deprecated. Use `amount` with an `amount_type` of `percent`. See Amount Types.
`hours_basis`	Which earnings’ hours count for per-hour benefits. See Defining Hours for Per-Hour Benefits.
`hours_includes`	Adds specific earning subtypes to the hours on top of `hours_basis`. Each entry sets a `type` of `earning` and a `subtype`.
`income_basis`	Which line items count as income for percentage benefits. See Defining Income for Percentage Benefits.
`income_includes`	Adds specific subtypes to the income on top of `income_basis`. Each entry sets a `type` (`earning`, `allowance`, or `reimbursement`) and a `subtype`.
`frequency`	How often the benefit applies: `once`, `per_payroll`, or `per_month`. See Frequency and Allocation.
`date_basis`	Which payroll date decides the calendar month for a `per_month` benefit.
`pay_period_cadence`	Which pay periods in the month receive a share of a `per_month` benefit.
`max_annual_contribution`	Optional annual contribution cap. See Contribution Limits.
`max_annual_contribution_basis`	Which earlier contributions count towards the cap. `this_benefit` (the default) or `all_line_items_of_type`.
`apply_sales_tax`	Adds provincial sales tax to the contribution. See Sales Tax on Contributions.
`remittance_account_id`	The remittance account these contributions are paid out to.
`expense_accounting_code_id`	Accounting code that routes the expense side of this benefit.
`liability_accounting_code_id`	Accounting code that routes the liability side of this benefit.

For the complete list of accepted fields, see the Create an Employer Benefit API reference.

🔍 Note: employee_benefit_id is used only for UI grouping. No values are inherited, and changes to one do not affect the other.

Employee Contributions

Employee Benefits represent the configuration of recurring contributions deducted from the employees earnings towards benefit plans, such as health insurance or retirement contributions.

They can be fixed amounts, amounts per hour worked, or calculated based on employee earnings.
During the effective dates, these contributions are automatically applied to the payroll as an Employee Benefit Line Item.
Employee Benefits can be inherited from a Business Preset, allowing for consistent benefit configurations across multiple work assignments.

Key Fields

Field	Description
`work_assignment_id`	Required. The work assignment this benefit applies to. Must belong to a work assignment associated with an entity of type Employee.
`business_preset_id`	Optional Business Preset to inherit from.
`employee_benefit_type`	The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`). Required unless inherited from a Business Preset.
`employer_benefit_id`	Optional reference to an employer_benefit used solely for display.
`title`	Label for identifying the benefit.
`effective_from`	Start date of the benefit.
`effective_to`	The end date for this plan (optional)
`amount`	The contribution value. Read against `amount_type`. See Amount Types.
`amount_type`	`fixed` for a dollar amount, `fixed_per_hour` for a dollar amount per hour, `percent` for a percentage of income. Defaults to `fixed`.
`percent`	Deprecated. Use `amount` with an `amount_type` of `percent`. See Amount Types.
`hours_basis`	Which earnings’ hours count for per-hour benefits. See Defining Hours for Per-Hour Benefits.
`hours_includes`	Adds specific earning subtypes to the hours on top of `hours_basis`. Each entry sets a `type` of `earning` and a `subtype`.
`income_basis`	Which line items count as income for percentage benefits. See Defining Income for Percentage Benefits.
`income_includes`	Adds specific subtypes to the income on top of `income_basis`. Each entry sets a `type` (`earning`, `allowance`, or `reimbursement`) and a `subtype`.
`frequency`	How often the benefit applies: `once`, `per_payroll`, or `per_month`. See Frequency and Allocation.
`date_basis`	Which payroll date decides the calendar month for a `per_month` benefit.
`pay_period_cadence`	Which pay periods in the month receive a share of a `per_month` benefit.
`max_annual_contribution`	Optional annual contribution cap. See Contribution Limits.
`max_annual_contribution_basis`	Which earlier contributions count towards the cap. `this_benefit` (the default) or `all_line_items_of_type`.
`apply_sales_tax`	Adds provincial sales tax to the contribution. See Sales Tax on Contributions.
`remittance_account_id`	The remittance account these contributions are paid out to.
`expense_accounting_code_id`	Accounting code that routes the expense side of this benefit.
`liability_accounting_code_id`	Accounting code that routes the liability side of this benefit.

For the complete list of accepted fields, see the Create an Employee Benefit API reference.

🔍 Note: employer_benefit_id is used only for UI grouping. No values are inherited, and changes to one do not affect the other.

Amount Types

A benefit contributes a dollar amount, a dollar amount per hour, or a percentage of income. amount carries the value and amount_type says how to read it.

fixed: amount is a dollar figure, up to 99999.
fixed_per_hour: amount is a dollar figure per hour. Nmbr multiplies it by the hours on the pay stub’s earning line items. See Defining Hours for Per-Hour Benefits.
percent: amount is a percentage between 0 and 100, applied to the income for the pay period.

amount_type defaults to fixed.

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "<work_assignment_id>",
        "employee_benefit_type": "pension_rrsp",
        "frequency": "per_payroll",
        "amount": 5,
        "amount_type": "percent",
        "income_basis": "regular_earnings",
        "effective_from": "2026-01-01"
     }'

Note: benefits used to carry a separate percent field, which is deprecated. Send amount with an amount_type of percent instead. While you migrate, you can pin either shape per request with a Prefer: deprecate_benefit_percent=true|false header.

Defining Hours for Per-Hour Benefits

hours_basis selects the earning line items on the pay stub whose hours count.

Value	Includes
`all_earnings`	The hours on every earning subtype. This is the default.
`regular_earnings`	The hours on the `salary` and `wage` earning subtypes.
`none`	Nothing. Use it with `hours_includes` to define the hours from scratch.

hours_includes adds specific earning subtypes on top of the basis. Each entry names a type of earning and a subtype. To count salary, wage and overtime hours, but not the hours on stat holiday pay or any other earning:

{
  "hours_basis": "regular_earnings",
  "hours_includes": [{ "type": "earning", "subtype": "overtime" }]
}

hours_basis and hours_includes only apply to per-hour benefits. Changing either one on any other benefit returns a validation error.

Defining Income for Percentage Benefits

A percentage benefit needs to know what counts as income. income_basis selects the line items on the pay stub that make up that figure.

Value	Includes
`regular_earnings`	The `salary` and `wage` earning subtypes. This is the default.
`all_earnings`	Every earning subtype.
`total_income`	Every earning subtype, plus taxable allowances and taxable reimbursements.
`none`	Nothing. Use it with `income_includes` to define income from scratch.

income_includes adds specific subtypes on top of the basis. Each entry names a type (earning, allowance, or reimbursement) and a subtype. To calculate a benefit on commissions alone, start from none and name the one subtype you want:

{
  "income_basis": "none",
  "income_includes": [{ "type": "earning", "subtype": "commission" }]
}

Income is measured on the pay stub being calculated, not year to date. A percentage benefit rises and falls with each period’s earnings.

Frequency and Allocation

frequency decides how often a benefit reaches a pay stub. Contributions are applied to the next regular draft payroll that falls inside the effective window.

once: applied to the next payroll, then not repeated once that payroll is no longer a draft.
per_payroll: the full amount on every payroll in the effective window.
per_month: the amount is divided across the selected payrolls in each calendar month.

per_month requires an amount_type of fixed. Percentage and per-hour benefits already recalculate against each period’s income or hours, so per_month would behave the same as per_payroll, and the API rejects the combination. Two fields shape a per_month allocation. date_basis decides which calendar month a payroll belongs to: by_period_start_date (the default), by_period_end_date, or by_pay_date. pay_period_cadence lists the pay periods in the month that receive a share, as 1-based positions. -1 means the final period of the month. When omitted, every period in the month receives a share.

Pay frequency	Available positions
Weekly	1, 2, 3, 4, -1
Bi-weekly	1, 2, -1
Semi-monthly	1, 2
Monthly	1

A $300 monthly benefit on a bi-weekly schedule with a `pay_period_cadence` of `[1, 2]` contributes $150 on each of the first two payrolls of the month, and nothing on a third. If a selected position doesn’t exist in a given month, its share is redistributed across the remaining selected periods. Both fields are read only for per_month fixed-amount benefits. Sending either one on any other benefit returns a validation error instead of storing a value that would never be used.

Sales Tax on Contributions

Ontario, Quebec, and Manitoba levy a sales tax on insurance premiums. Set apply_sales_tax to true and Nmbr adds that tax to the contribution, using the rate for the employee’s province of residence, the benefit type, and the payroll year. The tax covers insurance benefit types such as health, dental, group_term_life_insurance, group_dependent_life_insurance, accident_insurance_plan, and critical_illness. Employees in other provinces, and benefit types with no rate for that province, contribute the untaxed amount. Sales tax is added before max_annual_contribution is applied, so the cap bounds the premium plus tax.

Contribution Limits

Each benefit can have a max_annual_contribution defined to set an annual limit, which is enforced during payroll processing. The payroll that reaches the limit contributes only what’s left of it, and later payrolls contribute nothing until the next tax year. max_annual_contribution_basis sets what the cap counts:

this_benefit (the default) counts only the line items this benefit created earlier in the tax year.
all_line_items_of_type counts every line item of the same benefit type on the work assignment earlier in the tax year. That includes line items created by other benefits of the same type and one-off line items added straight to a pay stub, so two separate RRSP plans on one work assignment count towards a single yearly limit.

Employee and employer caps are independent. A linked pair of benefits does not share one limit, even when both sides fund the same plan. Other behaviour worth knowing:

The limit resets at the start of each tax year. For Canadian business entities that is the calendar year, measured on the payroll’s pay date.
Only line items on approved payrolls count towards the limit, including those since paid. A draft payroll doesn’t consume the cap until it is approved.
Where a line item’s amount was overridden with custom_amount, the overridden amount is what counts.
Changing max_annual_contribution mid-year changes the limit, not the remaining amount. Contributions already made this tax year count towards the new value, so lowering it below what has been contributed stops contributions until the next tax year.
Contributions recorded outside Nmbr are not considered. Year-to-date figures come from pay stubs in Nmbr only.

Validations

amount must be between 0 and 100 when amount_type is percent, and between 0 and 99999 when it is fixed or fixed_per_hour.
max_annual_contribution must be between 0 and 99999.99, with at most two decimal places.
Only one of amount or percent may be set per benefit. Attempts to set both will result in a validation error.
A benefit must include a *_benefit_type unless inherited from a Business Preset.
frequency may only be per_month when amount_type is fixed.
date_basis and pay_period_cadence may only be set on per_month fixed-amount benefits.
hours_basis and hours_includes may only be changed on fixed_per_hour benefits.
effective_to must be on or after effective_from.
The work assignment must belong to an Employee. Benefits are not available on contractor work assignments.

Benefit Line Items

Employer Benefit Line Items

Employer Benefit Line Items represent the actual contributions made by the employer towards employee benefit plans during payroll processing. These line items are generated based on the configured Employer Benefits, or can be created directly for one-time contributions.

Field	Description
`business_preset_id`	Optional Business Preset to inherit from.
`employer_benefit_type`	The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`)
`recurrence`	The employer benefit which generated this line item (read-only)
`title`	Label for identifying the benefit line item.
`amount`	Actual dollar value for this line item (read-only)
`custom_amount`	User settable value for the line item amount, always takes precedence over `managed_amount`
`managed_amount`	The calculated value for this line item.

Employee Benefit Line Items

Employee Benefit Line Items represent the actual contributions made by the employee towards benefit plans during payroll processing. These line items are generated based on the configured Employee Benefits, or can be created directly for one-time contributions.

Field	Description
`business_preset_id`	Optional Business Preset to inherit from.
`employee_benefit_type`	The type of benefit (e.g. `health`, `pension_rrsp`, `group_term_life_insurance`)
`recurrence`	The employee benefit which generated this line item (read-only)
`title`	Label for identifying the benefit line item.
`amount`	Actual dollar value for this line item (read-only)
`custom_amount`	User settable value for the line item amount, always takes precedence over `managed_amount`
`managed_amount`	The calculated value for this line item.

Benefit Types

Employee and employer benefits each have their own set of supported benefit types, which may overlap. You can retrieve the lists using the following endpoints:

GET /employee_benefit_types: Returns all employee benefit types
GET /employer_benefit_types: Returns all employer benefit types

Each benefit type object includes:

type: the unique identifier used in the API, e.g. critical_illness, pension_dcpp.
label: a human-readable name for display purposes, e.g “Critical Illness”, “Defined Contribution Pension Plan (DCPP)”.

Example Scenarios

A. One-Time Dental Contribution

Creates a one-time $125 employee-only dental benefit:

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "<work_assignment_id>",
        "employee_benefit_type": "dental",
        "frequency": "once",
        "amount": 125,
        "effective_from": "2025-04-01",
        "title": "Employee Dental Plan Contribution"
     }'

Recurring Employee RRSP contribution

A recurring RRSP contribution of $150 each payroll with an annual maximum of $600, starting from January 1, 2025:

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "<work_assignment_id>",
        "employee_benefit_type": "pension_rrsp",
        "frequency": "per_payroll",
        "amount": 150,
        "max_annual_contribution": 600,
        "effective_from": "2025-01-01"
     }'

Two RRSP plans under one annual cap

An employee contributes to two RRSP plans and the combined total must stay under $5,000 for the year. Set the same cap on both benefits with a basis of all_line_items_of_type, and every RRSP line item on the work assignment counts towards it:

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "<work_assignment_id>",
        "employee_benefit_type": "pension_rrsp",
        "frequency": "per_payroll",
        "amount": 200,
        "max_annual_contribution": 5000,
        "max_annual_contribution_basis": "all_line_items_of_type",
        "effective_from": "2026-01-01",
        "title": "Group RRSP"
     }'

Monthly health premium on the last payroll of the month

A $120 monthly employer health premium, allocated in full to the final payroll of each calendar month, with provincial sales tax added:

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employer_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "<work_assignment_id>",
        "employer_benefit_type": "health",
        "frequency": "per_month",
        "amount": 120,
        "amount_type": "fixed",
        "pay_period_cadence": [-1],
        "date_basis": "by_pay_date",
        "apply_sales_tax": true,
        "effective_from": "2026-01-01"
     }'

Employer pension contribution per hour worked

A $2.50 employer pension contribution for every hour worked, counting salary, wage and overtime hours but not stat holiday pay or paid leave:

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employer_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "<work_assignment_id>",
        "employer_benefit_type": "pension_dcpp",
        "frequency": "per_payroll",
        "amount": 2.50,
        "amount_type": "fixed_per_hour",
        "hours_basis": "regular_earnings",
        "hours_includes": [{ "type": "earning", "subtype": "overtime" }],
        "effective_from": "2026-01-01"
     }'

An employee who works 80 regular hours and 6 overtime hours in a pay period gets a $215.00 contribution.

Shared Health Plan

A recurring Health contribution:

Employer contributes $50 per payroll.
Employee contributes $25 per payroll.
The two benefits are linked, allowing the two benefits to be displayed together in payroll.

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employer_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "<work_assignment_id>",
        "employer_benefit_type": "health",
        "frequency": "per_payroll",
        "amount": 50,
        "effective_from": "2025-01-01"
     }'

curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/employee_benefits \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "work_assignment_id": "<work_assignment_id>",
        "employer_benefit_id": "<employer_benefit_id>",
        "employee_benefit_type": "health",
        "frequency": "per_payroll",
        "amount": 25,
        "effective_from": "2025-01-01"
     }'

Getting Started

Payroll Fundamentals

Canadian Payroll

Advanced Concepts

Accounting

Usage & Billing

Configuring Benefits

Employer Contributions

Employer Benefits

Employee Contributions

Key Fields

Amount Types

Defining Hours for Per-Hour Benefits

Defining Income for Percentage Benefits

Frequency and Allocation

Sales Tax on Contributions

Contribution Limits

Validations

Benefit Line Items

Employer Benefit Line Items

Employee Benefit Line Items

Benefit Types

Example Scenarios

A. One-Time Dental Contribution

Recurring Employee RRSP contribution

Two RRSP plans under one annual cap

Monthly health premium on the last payroll of the month

Employer pension contribution per hour worked

Shared Health Plan

​Employer Contributions

​Employer Benefits

​Employee Contributions

​Key Fields

​Amount Types

​Defining Hours for Per-Hour Benefits

​Defining Income for Percentage Benefits

​Frequency and Allocation

​Sales Tax on Contributions

​Contribution Limits

​Validations

​Benefit Line Items

​Employer Benefit Line Items

​Employee Benefit Line Items

​Benefit Types

​Example Scenarios

​A. One-Time Dental Contribution

​Recurring Employee RRSP contribution

​Two RRSP plans under one annual cap

​Monthly health premium on the last payroll of the month

​Employer pension contribution per hour worked

​Shared Health Plan

Employer Contributions

Employer Benefits

Employee Contributions

Key Fields

Amount Types

Defining Hours for Per-Hour Benefits

Defining Income for Percentage Benefits

Frequency and Allocation

Sales Tax on Contributions

Contribution Limits

Validations

Benefit Line Items

Employer Benefit Line Items

Employee Benefit Line Items

Benefit Types

Example Scenarios

A. One-Time Dental Contribution

Recurring Employee RRSP contribution

Two RRSP plans under one annual cap

Monthly health premium on the last payroll of the month

Employer pension contribution per hour worked

Shared Health Plan