> ## Documentation Index > Fetch the complete documentation index at: https://docs.nmbr.co/llms.txt > Use this file to discover all available pages before exploring further. # Tax Properties > Managing Business Entity and Work Assignment tax properties 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 ```bash theme={null} curl --request GET \ --url https://sandbox.nmbr.co/services/payroll/business_entities/be_01jb24442merpk8byaxjpvk1j7 \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ ``` ### Response ```json theme={null} { "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": "https://sandbox.nmbr.co/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 ```bash theme={null} curl --request GET \ --url https://sandbox.nmbr.co/services/payroll/tax_property_templates/ca::province_of_employment \ --header 'Authorization: Bearer ' \ --header 'accept: application/json' \ --header 'content-type: application/json' \ ```
View JSON Response ```json theme={null} { "id": "ca::province_of_employment", "object": "tax_property_template", "data": { "type": "ca::province_of_employment", "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", "nullable": false }, "links": { "self": "https://sandbox.nmbr.co/services/payroll/tax_property_templates/ca::province_of_employment" } } ```
*** ## 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.