Skip to main content
​
March 2026

​
Fields and features being removed after May 15, 2026

🚧 Breaking Change Several fields and features will be removed after May 15, 2026. Most of these are older, legacy fields and features that were repaced with newer ones in 2025, but without a formal deprecation notice. Most partners will already be using the newer fields and features and will not need to make changes as a result. However, it’s important to review each change to be sure.

​
Removing employer_ei_multiplier from business entity resources

We’re removing the employer_ei_multiplier read-only field from business entity resources (/business_entities, /business_entities/:id, and business_entity fields expanded in other resources).We now support having multiple CRA RP account numbers within a single business entity. As part of that feature, we now support managing a reduced EI rate through tax properties on the relevant CRA remittance account. For more information, see the EI Rate Reduction documentation.

​
Removing tax_jurisdiction from work assignment resources

We’re removing the tax_jurisdiction field from work assignment resources (/work_assignments, /work_assignments/:id, and work_assignment fields expanded in other resources).A work assignment may work in different tax jurisdictions in different pay periods. Having a single tax_jurisdiction value prevented tracking the tax jurisdiction over time or scheduling changes to it.Instead of setting tax_jurisdiction, manage a work assignment’s Province of Employment (POE) through its ca::province_of_employment tax properties.ℹ️ We are not removing the read-only current_tax_jurisdiction field as part of these changes. This field returns the value of the work assignment’s current ca::province_of_employment tax property for convenience.

​
Removing is_cpp_exempt and is_ei_exempt from work assignment resources

We’re removing the is_cpp_exemptand is_ei_exempt fields from work assignment resources (/work_assignments, /work_assignments/:id, and work_assignment fields expanded in other resources).A work assignment may be CPP-exempt or EI-exempt in some pay periods but not others. Having single is_cpp_exempt and is_ei_exempt values prevented tracking or scheduling changes to CPP-exempt and EI-exempt status over time.Instead of setting is_cpp_exempt or is_ei_exempt, manage a work assignment’s CPP-exempt and EI-exempt statuses through its ca::cpp_exempt and ca::ei_exempt tax properties.ℹ️ QPP- and QPIP-exempt status is already managed through tax properties.

​
Removing employee_summary.deductions and employee_summary.deductions_ytd from pay stub resources

We’re removing the employee_summary.deductions and employee_summary.deductions_ytd fields from pay stub resources (/pay_stubs, /pay_stubs/:id, and pay_stub fields expanded in other resources).These fields are poorly-named. Their names suggest they’re the sum of deduction line items on the pay stub (or pay stubs year-to-date), but they’re actually the sum of any line item subtracted from the employee’s pay, i.e. deduction, employee benefit, and employee statutory withholding line items.You can get the same information from the employee_summary.subtractions and employee_summary.subtractions_ytd fields respectively.

​
Removing support for creating forms identifying owner with work_assignment_id

We’re removing support for creating a form (POST /forms) using a work_assignment_id field to identify the owner of the form.When we first added support for forms, we only supported work assignment-level forms (e.g. TD1 and TP-1015.3-V), and so only ever needed work_asignment_id. Now that we support employee-level forms (e.g. T4 and ROE), we need different identifiers for different forms.Instead of sending a work_assignment_id on the request
POST /forms

{
  "work_assignment_id": "wrkas_...",
  ...
}
send the appropriate value in owner_id:
POST /forms

{
  "owner_id": "wrkas_...", // work assignment identifier for work assignment-level forms, etc
  ...
}

​
Removing work_assignment from form resources

We’re removing the work_assignment field from form resources (/forms, /forms/:id, and form fields expanded in other resources).Use the owner field to determine the owner of the form.

​
Removing support for expanding all line items on a pay stub with ?expand=line_items

We’re removing support for expanding all line items on a pay stub in a single line_items field using /pay_stubs?expand=line_items or /pay_stub/:id?expand=line_items.Each type of line item has a unique shape, and adding new types of line items could break consumers who aren’t expecting their shapes. Additionally, some use cases only require certain types of line items, and returning all line items is unnecessarily expensive. Instead of using expand=line_items to expand the line items, use expand=<type>_line_items,<type>_line_items,... for each type of line item you want returned.

​
Removing t4_code from allowance type resources

We’re removing the t4_code field from allowance type resources (/allowance_types, /allowance_types/:id, and allowance_type fields expanded in other resources).Where an allowance is reported on a T4 isn’t a simple 1:1 mapping. This field was always previously returned with the value null. The form_mappings field contains more nuanced information about how types map to forms.

​
Removing is_taxable, is_insurable, and is_pensionable from allowance type resources

We’re removing the is_taxable, is_insurable, and is_pensionable fields from allowance type resources (/allowance_types, /allowance_types/:id, and allowance_type fields expanded in other resources).Whether or not an allowance type is taxable, insurable, or pensionable isn’t a simple boolean value; it varies by jurisdiction. We’ve replaced these fields with a new Line Item Type Features system that will return more nuanced information about line item types in each jurisdiction we support.

​
Removing t4_code from deduction type resources

We’re removing the t4_code field from deduction type resources (/deduction_types, /deduction_types/:id, and deduction_type fields expanded in other resources).Where a deduction is reported on a T4 isn’t a simple 1:1 mapping. This field was always previously returned with the value null. The form_mappings field contains more nuanced information about how types map to forms.

​
Removing t4_code from reimbursement type resources

We’re removing the t4_code field from reimbursement type resources (/reimbursement_types, /reimbursement_types/:id, and reimbursement_type fields expanded in other resources).Where a reimbursement is reported on a T4 isn’t a simple 1:1 mapping. This field was always previously returned with the value null. The form_mappings field contains more nuanced information about how types map to forms.

​
Removing the is_taxable, is_insurable, and is_pensionable from reimbursement type resources

We’re removing the is_taxable, is_insurable, and is_pensionable fields from reimbursement type resources (/reimbursement_types, /reimbursement_types/:id, and reimbursement_type fields expanded in other resources).Whether or not a reimbursement type is taxable, insurable, or pensionable isn’t a simple boolean value; it varies by jurisdiction. We’ve replaced these fields with a new Line Item Type Features system that will return more nuanced information about line item types in each jurisdiction we support.

​
Removing journal entry line item report

We’re removing the journal entry line item report (POST /reports/journal-entry-line-item).It has been replaced by the Journal Entry Report.

​
Removing amount_override from line item resources

We’re removing the amount_override field from all line item resources:
  • /allowance_line_items/:id
  • /deduction_line_items/:id
  • /earning_line_items/:id
  • /employer_statutory_withholding_line_items/:id
  • /reimbursement_line_items/:id
  • /statutory_withholding_line_items/:id
These fields were for backward-compatibility during the transition from amount and amount_override to managed_amount, custom_amount, and amount in early 2025.Use the custom_amount field instead.
​
January 2026

​
name Read-Only amount and hours Properties on Line Items

🚧 Breaking Change The amount and hours properties on Line Items will be read-only as of March 1, 2026.

​
Read-Only amount and hours Properties on Line items

​
Introduction

In Nmbr, each type of line item has 3 “amount” properties:
  • managed_amount: The managed amount for the line item. The value is either calculated by the system (e.g. statutory holiday pay or vacation pay payout) or configured on the line item’s recurrence (e.g. a recurring allowance’s amount). This property is read-only.
  • custom_amount: The custom amount for the line item.
  • amount: The final amount for the line item. This is the amount that will be paid, deducted, withheld, etc. The value will be custom_amount, if set, and managed_amount otherwise.
Similarly, the earning line item type has 3 “hours” properties:
  • managed_hours: The managed hours for the line item. This amount is the default number of hours on the line item’s Pay Rate. This property is read-only.
  • custom_hours: The custom hours for the line item. custom_hours can be used to prorate the dollar amount on salary line items with a Pay Rate.
  • hours: The final hours for the line item. The value will be custom_hours, if set, and managed_hours otherwise.
Currently, the amount and hours properties are read/write. If you create or update a line item with an amount or hours value, the line item’s custom_amount or custom_hours values will be set.

​
What’s Changing

On March 1, 2026 we will be changing the amount and hours properties to be read-only. If you create or update a line item with amount or hours values, these values will be ignored.If your application sends amount or hours properties in requests to create or update line items, you will need to rename amount to custom_amount and hours to custom_hours in requests.For example, if you make the following request to create an earning line itemPOST /earning_line_items
{
    ...
    "amount": 500,
    "hours": 10,
    ...
}
you would need to rename the properties as followsPOST /earning_line_items
{
    ...
    "custom_amount": 500,
    "custom_hours": 10,
    ...
}

​
What’s Not Changing

We will continue sending the computed amount and hours values in responses. Your application can continue to rely on these values.GET /earning_line_items/ernli_01KBG99GP45784S1PVZTAGFE6X
{
    ...
    "managed_amount": 1000,
    "managed_hours": 20,
    ...
    "custom_amount": 500,
    "custom_hours": 10,
    ...
    "amount": 500,           // computed from managed_amount and custom_amount
    "hours: 10,              // computed from managed_hours and custom_hours
    ...
}
​
September 2025

​
name Property Required on Business Presets

🚧 Breaking Change The name property on Business Presets will be required as of November 15th, 2025.

​
name Property Required on Business Presets

Business Presets currently require a value for either the title property or the name property.
  • title is copied to recurrences (pay rates, allowances, employee and employer benefits, deductions, and reimbursements) and line items, and used as their title.
  • name is used to identify the preset in the component or portal, or when grouping line items by preset on pay stubs or reports. If a Business Preset doesn’t have a name, we currently fall back on title.
We will be making the name property required as of November 15th, 2025 and removing the logic that currently falls back to title. In order to create new Business Presets, you will need to supply a value for name.The title property will continue to be optional.

​
Business Entity-level templates deprecated

🚧 Breaking Change Business Entity-level templates for Allowances, Benefits, Deductions, and Reimbursements have been deprecated and will be removed on November 15, 2025. Please migrate to the new Business Presets feature. Legacy endpoints will continue to function until this date but will not receive updates or bug fixes.

​
Deprecation of Business Entity-Level Templates for Allowances, Benefits, Deductions, and Reimbursements

Nmbr previously supported defining templates for Allowances, Benefits, Deductions, and Reimbursements at the Business Entity level. As part of improving our API and providing a more consistent experience, we are replacing this feature with the new Business Presets feature, which supports a larger set of use cases with fewer endpoints.

​
Deprecated Endpoints

The following endpoints are now deprecated and have been replaced by the new Business Presets endpoints:
  • /business_entity_allowances
  • /business_entity_benefits
  • /business_entity_deductions
  • /business_entity_reimbursements

​
Migration

​
Data

You do NOT need to perform a data migration from legacy templates to Business Presets.When Business Presets were released, legacy templates were migrated to Business Presets of the appropriate type. For example, every legacy template for Allowances was migrated to a Business Preset of type allowance.To maintain backward compatibility, the APIs for these features were changed to manage Business Presets of the appropriate type. For example, creating/updating/deleting a Business Preset of type allowance will appear to create/update/delete a legacy template for Allowances, and vice versa. However, behind the scenes there is actually only one record in the Nmbr system: the Business Preset.During this migration, the ULIDs for legacy templates were retained as the ULID for the corresponding Business Preset, so partners will not need to store two ULID values (legacy template ULID and Business Preset ULID) or map between them.

​
API

You DO need to perform a code migration to change any code that is currently calling the legacy template APIs to instead call the Business Presets APIs.

​
Allowances

Change any code calling the /business_entity_allowances endpoints with the property "allowance_type": "T" to instead call the corresponding /business_presets endpoints with the properties "type": "allowance" and "subtype": "T".For example, if you’re working with taxable meals allowances, "allowance_type": "meals_taxable" will become "type": "allowance" and "subtype": "meals_taxable".As mentioned in the data section above, you can continue to use the ULIDs for legacy templates.| Action | Old Endpoint | New Endpoint | |||| | | name | New required property. All Business Presets must have a name. The name is used when listing Business Presets and when grouping line items by Business Preset. | | | type | New required property. For allowances, the type is always allowance. | | allowance_type | subtype | Renamed. | | business_entity_id | business_entity_id | Unchanged. | | title | title | Unchanged. |

​
Benefits

Since Business Presets were released, Benefits were split into separate Employer Benefits and Employee Benefits.For Employer Benefits, change any code calling the /business_entity_benefits endpoints with the property "benefit_type": "T" to instead call the corresponding /business_presets endpoints with the properties "type": "employer_benefit" and "subtype": "T".| Action | Old Endpoint | New Endpoint | |||| | Create | POST /business_entity_benefits with body { "benefit_type": "T", ... } | POST /business_presets with body { "type": "employee_benefit", "subtype": "T", ... } | | List | GET /business_entity_benefits | GET /business_presets?type=employee_benefit | | Retrieve | GET /business_entity_benefits/:ulid | GET /business_presets/:ulid | | Update | PUT /business_entity_benefits/:ulid | PUT /business_presets/:ulid | | Delete | DELETE /business_entity_benefits/:ulid | DELETE /business_presets/:ulid |The legacy benefit template properties map to the Business Presets properties as follows:| Old Property | New Property | Notes | |||| | Create | POST /business_entity_deductions with body { "deduction_type": "T", ... } | POST /business_presets with body { "type": "deduction", "subtype": "T", ... } | | List | GET /business_entity_deductions | GET /business_presets?type=deduction | | Retrieve | GET /business_entity_deductions/:ulid | GET /business_presets/:ulid | | Update | PUT /business_entity_deductions/:ulid | PUT /business_presets/:ulid | | Delete | DELETE /business_entity_deductions/:ulid | DELETE /business_presets/:ulid |The legacy deduction template properties map to the Business Presets properties as follows:| Old Property | New Property | Notes | |||| | Create | POST /business_entity_reimbursements with body { "reimbursement_type": "T", ... } | POST /business_presets with body { "type": "reimbursement", "subtype": "T", ... } | | List | GET /business_entity_reimbursements | GET /business_presets?type=reimbursement | | Retrieve | GET /business_entity_reimbursements/:ulid | GET /business_presets/:ulid | | Update | PUT /business_entity_reimbursements/:ulid | PUT /business_presets/:ulid | | Delete | DELETE /business_entity_reimbursements/:ulid | DELETE /business_presets/:ulid |The legacy reimbursement template properties map to the Business Presets properties as follows:| Old Property | New Property | Notes | ||---| | | name | New required property. All Business Presets must have a name. The name is used when listing Business Presets and when grouping line items by Business Preset. | | | type | New required property. For reimbursements, the type is always reimbursement. | | deduction_type | subtype | Renamed. | | business_entity_id | business_entity_id | Unchanged. | | title | title | Unchanged. |

​
Deprecation of Legacy Benefits API

🚧 Breaking Change
The legacy Benefits API has been deprecated and will be removed on August 31, 2025.
Please use the new Benefits API endpoints for all benefit-related operations. Legacy endpoints will continue to function until this date but will not receive updates or bug fixes.

​
Deprecation of Legacy Benefits API

As part of improving our API and providing a more consistent experience, we are deprecating the legacy Benefits endpoints. We have split the functionality into two distinct sets of API endpoints: one for employers and one for employees. This allows us to better align the Benefits functionality with our existing API structure.All existing data has been migrated to the new endpoints, and you can continue to access your employee and employer benefits data without interruption. All existing Benefit and Benefit Line Item ULIDs have been preserved on the corresponding Employee Benefit and Employee Benefit Line Item records.More information can be found in the Configuring Benefits documentation.As well as providing a more consistent API experience, these changes are required to offer improved functionality for reporting and GL code mapping.

​
Legacy Benefits API Deprecation

The following endpoints are now deprecated and have been replaced by the new Employee and Employer Benefits API endpoints:
  • /benefits → replaced by:
    • /employee_benefits
    • /employer_benefits
  • /benefit_line_items → replaced by:
    • /employee_benefit_line_items
    • /employer_benefit_line_items
  • /benefit_types → replaced by:
    • /employee_benefit_types
    • /employer_benefit_types

​
Benefit Types

Previously, a single benefit_type was used to categorize benefits. This did not correctly represent benefits as they are used in the real world. Some benefits are contributed to by both the employer and employee, while others are only contributed to by one party. This ambiguity made accurate reporting and accounting more difficult.To address this, we have introduced two new benefit types: employee_benefit_type and employer_benefit_type. The two benefit types now contain different values, reflecting the distinct contributions made by employees and employers. For example, pension_rrsp may appear in both employee_benefit_type and employer_benefit_type, whereas gift_near_cash will only appear in employer_benefit_type.These changes not only provide a more consistent API experience but also enable improved reporting and GL code mapping.
​
May 2025

​
Updates to Line Item Type Filters

🚧 Breaking Change Type filters in Line Item listing endpoints have been replaced with include_types. The deprecated filters listed below will be removed on June 30, 2025.

​
Renamed Type Filters for Line Item Listings

The following query parameters have been renamed to include_types for consistency across line item listing endpoints:

​
New Filtering Options

All line item listing endpoints now support both:
  • include_types: Return only items matching one or more specified types. Example: Retrieve only wage and overtime earnings.
  • exclude_types: Exclude items of one or more specified types from the results. Example: Omit union_dues from deduction results.
These changes promote consistency and improve filtering flexibility across the API.
​
April 2025

​
Additional Validation on Date Fields

🚧 Breaking Change Additional validation will be performed on date fields as of May 1st, 2025.

​
Additional Validation on Date Fields

Our API accepts and returns date-related fields following the ISO 8601 standard:
  • date fields are formatted YYYY-MM-DD without a time component (e.g. 2023-01-01)
  • date-time fields are formatted YYYY-MM-DDThh:mm:ss.sssZ (e.g. 2023-01-01T06:30:00.000000Z)
However, some endpoints are not currently validating the format of some date fields, and are accepting the date-time format or other formats.We will be introducing validation on these fields beginning May 1, 2025, and accepting only the date format after that.The following key fields have been identified as changing:
  • When creating or updating employees, the date_of_birth field must be formatted YYYY-MM-DD.
  • When creating or updating allowances, benefits, deductions, reimbursements, or pay rates, the effective_from and effective_to fields must be formatted YYYY-MM-DD.
  • When creating or updating pay schedules, the anchor_pay_date and anchor_end_of_pay_period fields must be formatted YYYY-MM-DD.
  • When terminating work assignments, the effective_date field must be formatted YYYY-MM-DD.
  • When filtering reports by pay date, the pay_date_from and pay_date_to fields must be formatted YYYY-MM-DD.
However, this change will apply to all fields documented as date in our documentation. Please ensure that date fields are properly formatted.

​
amount Required on Reimbursements

🚧 Breaking Change amount field required on reimbursements as of May 30th, 2025.

​
amount Required on Reimbursements

When creating reimbursements, the amount field is not currently a required field.We will be making the amount field a required field beginning May 30, 2025, and requiring a value for the field after that.Please ensure the amount field is supplied when creating reimbursements.
​
March 2025

​
Deprecating Vacation Pay on Pay Rates

🚧 Deprecation Notice Vacation Pay on Pay Rates is being deprecated and will be removed on May 15th, 2025.

​
Deprecating Vacation Pay on Pay Rates

As part of improvements to functionality for Vacation Pay, we have deprecated the Vacation Pay attributes on the Pay Rate entity.
  • vacation_pay_percentage - this attribute is deprecated and has been removed.
  • vacation_pay_method - this attribute is deprecated and has been removed.
These changes will take effect on May 15th, 2025.

​
Migrating to Vacation Pay Settings

To manage the vacation pay percentage and payout methods for a Work Assignment, you can use the vacation_pay_settings endpoint. This entity will allow you to set the percentage, the effective dates, and method of vacation pay for a specific Work Assignment.All eligible earning line items will have vacation pay calculated based on the active Vacation Pay Setting and the Province of Employment for the Work Assignment.To read more, please see the Vacation Pay Guide.
​
July 2024

​
Standardizing Historical Payroll Terminology

We’ve standardized on the term “historical payroll” for payrolls run with a different provider in the current calendar year. To create a historical payroll, a post request should use the type: historical. View docs.
​
May 2024

​
Updates to Future PayStub Line Items

Enhanced Line Item Generation: We’ve refined the generation process for recurring line items on future Pay Stubs. Now, line items for recurring Earnings, Benefits, Reimbursements, Allowances, and Deductions will automatically populate once the preceding payroll changes status to paid. This ensures that your upcoming Pay Stubs reflect the most current and accurate information.

​
Changes to Validation on Pay Rates

Required expected_hours_per_week Field: To improve the accuracy of Statutory Withholdings for off-cycle Payrolls, the expected_hours_per_week field is now mandatory when creating a new Pay Rate. This update helps minimizing discrepancies and potential errors in payroll processing.