Skip to main content
When working with Payroll, it is important to configure Business Entities and Work Assignments to ensure accurate tax calculations. The Nmbr API uses Tax Properties to manage these configurations effectively. For example, you might set the Province of Employment for a Business Entity and later update it if the business relocates. The Nmbr API enables accurate configuration and management of such attributes through Tax Properties.

​
Viewing Available Tax Properties

Resources that support Tax Properties include an available_tax_properties attribute. This attribute contains a list of Tax Property keys that can be managed for the specific resource instance. For example, when retrieving a Business Entity, the available_tax_properties attribute lists Template keys that can be used to create Tax Properties for the Business Entity.

​
Request

curl --request GET \
     --url https://sandbox.nmbr.co/services/payroll/business_entities/be_01jb24442merpk8byaxjpvk1j7 \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \

​
Response

{
    "id": "be_01jb24442merpk8byaxjpvk1j7",
    "object": "business_entity",
    "data": {
        "business_number": "294273965RP4161",
        "name": "Consulting Corp.",
        "available_tax_properties": [
            "ca::province_of_employment",
            "ca::ei_premium_reduction",
            "ca::bc::eht",
        ],
        "created_at": "2024-10-25T15:17:20.000000Z",
        "updated_at": "2024-10-25T15:17:20.000000Z"
    },
    "links": {
        "self": "http://localhost/services/payroll/business_entities/be_01jb24442merpk8byaxjpvk1j7"
    }
}
To configure a Tax Property, retrieve its template using the /tax_property_templates endpoint. The response provides detailed information about the template, including:
  • label: A user-friendly display name for the Tax Property.
  • format: The expected data format for the value (e.g., string, boolean, numeric, date).
  • options: If the Tax Property accepts only specific values, they will be listed as key-value pairs.
  • allow_concurrent: Indicates whether multiple active Tax Properties can coexist for the same entity during overlapping date periods.
  • nullable: Specifies whether the value can be set to null.

​
Creating a Tax Property

Use the /tax_properties endpoint to create a new Tax Property. Required parameters include:
  • owner_id: The ULID of the resource (e.g., Business Entity or Work Assignment) associated with the Tax Property.
  • type: The template type value (e.g., ca::province_of_employment, ca::mb::eht).
  • effective_from: The date this Tax Property becomes effective. Tax Properties are applied based on their effective dates relative to the pay_date of a payroll.

​
Request

curl --request GET \
     --url https://sandbox.nmbr.co/services/payroll/tax_property_templates/ca::province_of_employment \
     --header 'Authorization: Bearer <access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \

​
Managing Tax Properties

Tax Properties are essential for calculating accurate taxes, contributions, and withholdings for employees and employers. They follow these rules:
  • Locked after payroll approval: Tax Properties cannot be updated or deleted once a payroll that uses the property is marked as approved.
  • Editable attributes: The is_editable attribute determines if a Tax Property can be modified. If false, only the effective_to date can be updated.
Each Tax Property inherits its allow_concurrent attribute from its template:
  • If allow_concurrent is true, you can create multiple Tax Properties for the same entity that overlap by date.
  • If allow_concurrent is false, you must delete or end the existing Tax Property before creating a new one. The new effective_from date must be after the previous Tax Property’s effective_to date.

​
Ending a Tax Property

To end the effectiveness of a Tax Property, set its effective_to date. This determines the last date the property will apply to payroll tax calculations. The Tax Property remains active for all relevant payrolls with a pay_date between the effective_from and effective_to dates, inclusive. When setting the effective_to date, it must not be earlier than the earliest_valid_effective_to, which is determined by how the property has been used:
  • The effective_from date, if the Tax Property has never been used in an approved payroll.
  • The pay_date of the most recent payroll that used it.
📘 Pay Dates and Tax Properties A Tax Property cannot be ended before the pay_date of the most recent payroll that used it. This is because tax calculations are based on the date the employee is paid, not when the work was performed.

​
Tax Property Priority

Some Tax Properties may be set at both the Business Entity and Work Assignment levels. Priority rules determine which value is applied:
  • Generally, Work Assignment Tax Properties take precedence over Business Entity Tax Properties when both are active for a given Payroll Pay Date.

​
Example

If the ca::province_of_employment Tax Property is set for both a Business Entity and a Work Assignment, the Work Assignment value is used to calculate provincial taxes for the employee.