Skip to main content
🚧 Deprecation Notice
This document outlines the new Tax Property–based approach for managing Province of Employment. A previous method of configuring a Province of Employment directly on a Business Entity or Work Assignment is deprecated and will be removed in a future release. Please see the migration guide in the section below.
When an employer pays employees income such as salaries, wages, or commissions, the employee’s Province of Employment (POE) and Province of Work (POW) must be correctly configured to ensure the proper deductions are withheld. The Province of Employment (POE) determines the application of:
  • Provincial income taxes
  • Provincial sales taxes on benefits
  • EHT contributions
The Province of Work (POW) determine the application of:
  • Vacation pay
  • Statutory holiday pay
  • WCB premiums

​
Province of Employment (POE)

​
Province of Employment on Business Entities

When creating a Business Entity, it is essential to set a default Province of Employment. This POE will be used to calculate the appropriate withholdings on all Work Assignments in the Business Entity by default. To configure the Province of Employment on the Business Entity, you must create a Tax Property with a type of ca::province_of_employment, and owner_id of the Business Entity.
❗️️Blocked Payrolls
Payroll approval will be blocked by a Warning if a Business Entity does not have a Province of Employment configured.
See Managing Tax Properties for details on how to create or update the Province of Employment.

​
Province of Employment on Work Assignments

If an Employee’s Work Assignment should use a different Province of Employment than the Business Entity, a Tax Property should be configured for the Work Assignment in question. To configure the Province of Employment on the Work Assignment, you must create a Tax Property with a type of ca::province_of_employment, and owner_id of the Work Assignment. This Tax Property will take precedence over any POE configured at the Business Entity level. See Managing Tax Properties for details on how to create or update the Province of Employment.

​
Province of Work (POW)

By default, an Employee’s Work Assignment will use its Province of Employment as its Province of Work. If the Work Assignment should use a different Province of Work, a Tax Property should be configured for the Work Assignment in question. To configure the Province of Work on the Work Assignment, you must create a Tax Property with a type of ca::province_of_work, and owner_id of the Work Assignment. See Managing Tax Properties for details on how to create or update the Province of Work.

​
Managing Tax Properties

A Province of Employment Tax Property has the following attributes:
FieldTypeRequiredDescription
owner_idstring (Nmbr ULID)✅ YesThe ID of the Business Entity or Work Assignment that you are configuring the POE for.
typestring✅ YesUse ca::province_of_employment.
valuestring✅ YesSee below for more details on valid values.
effective_fromdate string (Y-m-d)✅ YesThe date this POE will take effect. See below for recommendations when setting this on newly created Business Entities.
effective_todate string (Y-m-d)❌ noThe final date this POE will be used.
Similarly, a Province of Work Tax Property has the following attributes:
FieldTypeRequiredDescription
owner_idstring (Nmbr ULID)✅ YesThe ID of the Work Assignment that you are configuring the POW for.

Note: Unlike POE, you can only create a POW Tax Property for a Work Assignment, not a Business Entity.
typestring✅ YesUse ca::province_of_work.
valuestring✅ YesSee below for more details on valid values.
effective_fromdate string (Y-m-d)✅ YesThe date this POW will take effect. See below for recommendations when setting this on newly created Business Entities.
effective_todate string (Y-m-d)❌ noThe final date this POW will be used.
For both POE and POW:
  • effective_from: When creating the first Province of Employment for a new Business Entity, it is suggested that the effective_from is set as the first day of the current year - e.g 2025-01-01. This can help avoid issues when onboarding companies with historical payrolls dated before their transition to Nmbr.
  • value: The value can be any of:
    • ca_ab - Alberta
    • ca_bc - British Columbia
    • ca_mb - Manitoba
    • ca_nb - New Brunswick
    • ca_nl - Newfoundland and Labrador
    • ca_ns - Nova Scotia
    • ca_nt - Northwest Territories
    • ca_nu - Nunavut
    • ca_on - Ontario
    • ca_pe - Prince Edward Island
    • ca_qc - Quebec
    • ca_sk - Saskatchewan
    • ca_yt - Yukon
The Tax Properties for Province of Employment and Province of Work do not support overlapping effective dates for the same owner. This means that before you can assign a new POE or POW to a Business Entity or Work Assignment, you must first end the current one by setting its effective_to date. When ending the Tax Property, you can use the earliest_valid_effective_to attribute to simplify selecting the new effective_to date. The earliest_valid_effective_to is the first date where this Tax Property has not been used on any non-draft Payroll (e.g. with a status of approved or paid) - as it is not possible to change the POE or POW on data in the past. Dates prior to earliest_valid_effective_to are considered invalid and will be rejected by the API. To avoid gaps that could result in payroll calculation errors, the effective_from date of the new Province of Employment or Province of Work should be set to the day immediately following the effective_to date of the previous one. If a Work Assignment’s Province of Employment is ended without a new one being assigned, it will automatically inherit the Province of Employment from the associated Business Entity. If a Work Assignment’s Province of Work is ended without a new one being assigned, it will automatically inherit the Province of Employment from the Work Assignment. If the Work Assignment’s POE has also been ended, it will inherit the POE from the associated Business Entity, as above.

​
Example Usage

Creating a Province of Employment for a Business Entity: 
curl --request POST \
     --url https://sandbox.nmbr.co/services/payroll/tax_properties \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '{
        "owner_id": "<nmbr_ulid>",
        "type": "ca::province_of_employment",
        "value": "ca_mb",
        "effective_from": "2026-01-01"
     }'

{
  "id": "txprp_01JV378Q2EDB8H720QW2KZ2QFJ",
  "object": "tax_property",
  "data": {
    "type": "ca::province_of_employment",
    "value": "ca_mb",
    "effective_from": "2026-01-01",
    "effective_to": null,
    "earliest_valid_effective_to": "2026-01-01",
    "is_editable": true,
    "is_deletable": true,
    "label": "Province Of Employment",
    "format": "string",
    "options": {
      "ca_ab": "Alberta",
      "ca_bc": "British Columbia",
      "ca_mb": "Manitoba",
      "ca_nb": "New Brunswick",
      "ca_nl": "Newfoundland and Labrador",
      "ca_ns": "Nova Scotia",
      "ca_nt": "Northwest Territories",
      "ca_nu": "Nunavut",
      "ca_on": "Ontario",
      "ca_pe": "Prince Edward Island",
      "ca_qc": "Quebec",
      "ca_sk": "Saskatchewan",
      "ca_yt": "Yukon"
    },
    "allow_concurrent": false,
    "feature": "onboarding",
    "owner": {
      "id": "be_01JN4M4FN41P11NQ1WS130Z2HT",
      "object": "business_entity",
      "links": {
        "self": "https://sandbox.nmbr.co/services/payroll/services/payroll/business_entities/be_01JN4M4FN41P11NQ1WS130Z2HT"
      }
    },
    "note": null,
    "created_at": "2025-05-12T21:43:56.000000Z",
    "updated_at": "2025-05-12T21:43:56.000000Z"
  },
  "links": {
    "self": "https://sandbox.nmbr.co/services/payroll/services/payroll/tax_properties/txprp_01JV378Q2EDB8H720QW2KZ2QFJ"
  }
}

​
Outside Canada (oc)

Under certain circumstances, a Business Entity or Work Assignment may have its Province of Employment or Province of Work set to Outside Canada (OC). Nmbr supports OC as a valid value for the Province of Employment and Province of Work Tax Properties (ca_oc). This corresponds to the CRA rules for a province of employment of “Outside Canada.” When Outside Canada is set as the Province of Employment, Nmbr will not calculate any provincial/territorial income taxes or EHT (or similar provincial payroll taxes) for the affected Work Assignments. Only the following statutory withholdings are calculated (where the employment is pensionable/insurable under CPP/EI, as per CRA guidelines):
  • Federal income tax
  • Canada Pension Plan (CPP) contributions
  • Employment Insurance (EI) premiums
By default, Nmbr will withhold federal income surtax when the Province of Employment is set to Outside Canada (48% of the calculated federal income tax). In some cases, an employer may want to disable the federal surtax withholding for a Work Assignment, or all Employees in a Business Entity with the Outside Canada Province of Employment. To achieve this, the Federal Surtax Exempt Tax Property can be created to enable. 
curl --request POST \
  --url https://sandbox.nmbr.co/services/payroll/tax_properties \
  --header 'Authorization: Bearer <access_token>' \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{
    "owner_id": "<nmbr_ulid>",
    "type": "ca::federal_oc_surtax_exempt",
    "value": true,
    "effective_from": "2026-01-01"
}'
Note: the value for the ca::federal_oc_surtax_exempt Tax Property can only be set to true. If this Tax Property is not created, Nmbr will withhold federal surtax by default for Employees with a Province of Employment of Outside Canada. Similarly, when Outside Canada is set as the Province of Work, Nmbr will not calculate any provincial vacation pay, statutory holiday pay, or WCB remittances.

​
Deprecated Province of Employment Configuration

Previously, Province of Employment was configured directly on Business Entity and Work Assignment records. However, this approach did not support date-based management and has been replaced by the Tax Property model. These approaches are now deprecated and will be removed in a future update - the Tax Property based approach must be implemented to avoid any disruption.

​
Changes to the Business Entity

  • The Province of Employment was previously determined from the Business Entities province, in the address.
  • This property may still be used to manage the province in the address, but will no longer be used to determine the POE.
  • All existing Business Entities should already have auto-generated POE Tax Properties. It is recommended to verify this during migration.
  • To retrieve the current Province of Employment for a Business Entity, use the current_tax_jurisdiction attribute.

​
Changes to the Work Assignments

  • The Province of Employment was previously configured using the tax_jurisdiction attribute.
  • Read and write access to this attribute will be removed in a future update.
  • All existing Work Assignments should already have auto-generated POE Tax Properties. It is recommended to verify this during migration.
  • To retrieve the current Province of Employment for a Work Assignment, use the current_tax_jurisdiction attribute.

​
Further Reading