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 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, `percent` for a percentage of income. Defaults to `fixed`.
`percent`	Deprecated. Use `amount` with an `amount_type` of `percent`. See Amount Types.
`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 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, `percent` for a percentage of income. Defaults to `fixed`.
`percent`	Deprecated. Use `amount` with an `amount_type` of `percent`. See Amount Types.
`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 either a dollar amount 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.
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 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. A percentage benefit already recalculates against each period’s income, 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

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 after max_annual_contribution is applied, so the cap bounds the premium rather than 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. Contributions stop once the limit is reached. max_annual_contribution_basis sets what the cap counts:

this_benefit (the default) counts only the line items this benefit created earlier in the year.
all_line_items_of_type counts every line item of the same benefit type on the work assignment earlier in the 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 paid payrolls count towards the limit. A draft payroll doesn’t consume the cap until it is paid.
Where a line item’s amount was overridden with custom_amount, the overridden amount is what counts.
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.
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.
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"
     }'

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

Shared Health Plan

​Employer Contributions

​Employer Benefits

​Employee Contributions

​Key Fields

​Amount Types

​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

​Shared Health Plan

Employer Contributions

Employer Benefits

Employee Contributions

Key Fields

Amount Types

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

Shared Health Plan