Sign in for full access

Finding Applicable Taxes

Part 2 of 3

Suggest Edits

Now that we know which location codes to use for Astrid, we can find the taxes that will potentially apply for this payroll.

We're going to be making a single request ("SetTaxListRequest") to the setTaxList endpoint:

https://ste-staging.symmetry.com/ste-hosted/v2/setTaxList

Sample SetTaxListRequest

The following request will return all potentially applicable taxes based on the two location codes listed above, as well as any unique parameters used in the calculation of those taxes:

{
  "SetTaxListRequest": {
    "taxReference": [
      {
        "locationCode": "80-000-0000",
        "payDate": "2023-01-13",
        "isResident": true,
        "municipalityCode": null,
        "schoolCode": null
      },
      {
        "locationCode": "82-000-0000",
        "payDate": "2023-01-13",
        "isResident": true,
        "municipalityCode": null,
        "schoolCode": null
      }
    ]
  }
}

SetTaxListRequest breakdown

Each object within the "taxReference" array has the following properties:

"locationCode"

One of the location codes that we determined in the previous step.

"payDate"

The actual date of the payroll in YYYY-MM-DD format. In the example above, we're assuming that Astrid's employer runs payroll on January 13, 2023 ("2023-01-13"). Since we're setting up multiple location codes here, we've also made sure that the date is the same for all three entries.

Note that because this is a string, it must be surrounded by quotation marks. You can't just enter 2023-01-13!

"isResident"

Since Astrid lives in British Columbia, we've entered true for both the federal and the British Columbia location codes.

"municipalityCode", "schoolCode"

Neither of those fields are used for Canadian calculations in the STE, so we've set both of these to null.

Sample SetTaxListResponse

After we send that request, we'll get the following lengthy response back from the STE:

{
  "SetTaxListResponse": {
    "taxItem": [
      {
        "rate": 0.0595,
        "annual_max": 66600,
        "isResident": true,
        "MaximumInsurable": 0,
        "max_contribution": 3754.45,
        "v1Rate": 0,
        "provinceAbbreviation": "CAN",
        "AverageAssessmentRate": 0,
        "basicAmount": 0,
        "max_contribution_period": 1,
        "provinceCode": "80",
        "LCPAmount": 0,
        "jurisdictionData": [
          {
            "regexType": "PickList",
            "parameterName": "DATE_OF_BIRTH",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "1900-01-01",
            "provinceAbbreviation": "CAN",
            "dataType": "String",
            "uniqueTaxID": "80-000-0000-CPP-000",
            "taxEffectiveDate": "1900-01-01",
            "regex": "^([12][0-9]{3}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01]))$",
            "certificateLineNo": "Publication T4001, Chapter 2, Special Situations",
            "description": "Date of Birth",
            "regexDescription": "Employee Date of Birth",
            "helpText": "Employee date of birth"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "CPP_DEDUCTIONS",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-CPP-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Federal CPP Deductions",
            "regexDescription": "Non-pensionable Earnings Deductions",
            "helpText": "Amounts that are not included in pensionable earnings, such as deductions allocated to a member of the clergy."
          },
          {
            "regexType": "PickList",
            "parameterName": "TRANSFERRED",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "FALSE",
            "provinceAbbreviation": "CAN",
            "dataType": "Boolean",
            "uniqueTaxID": "80-000-0000-CPP-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^(TRUE|FALSE)$",
            "certificateLineNo": "Publication T4127, Employees who were transferred by their employer from Quebec to a location outside Quebec during the year",
            "description": "Quebec-Employee Transferred Outside Quebec",
            "regexDescription": "'True' or 'False'",
            "helpText": "A flag for transferring employees. Set to 'True' for Quebec employees transferred outside Quebec during the year."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "COMMISSION_DURATION",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Integer",
            "uniqueTaxID": "80-000-0000-CPP-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+)$",
            "certificateLineNo": "Publication T4127, Factor N",
            "description": "Number of Days Since Last Commission Payment",
            "regexDescription": "Number of Days Since Last Commission Payment",
            "helpText": "N, The number of days since the last commission payment. The minimum basic exemption amount of $67.30 is included in the formula in line with CPP legislation"
          }
        ],
        "country": "CA",
        "description": "Canada Pension Plan Tax",
        "taxEffectiveDate": "2023-01-01",
        "isEmployerTax": false,
        "uniqueTaxID": "80-000-0000-CPP-000",
        "provinceName": "Canadian Federal",
        "LCPRate": 0
      },
      {
        "rate": 0.0163,
        "annual_max": 61500,
        "isResident": true,
        "MaximumInsurable": 0,
        "max_contribution": 1002.45,
        "v1Rate": 0,
        "provinceAbbreviation": "CAN",
        "AverageAssessmentRate": 0,
        "basicAmount": 0,
        "max_contribution_period": 1,
        "provinceCode": "80",
        "LCPAmount": 0,
        "jurisdictionData": [
          {
            "regexType": "SingleValue",
            "parameterName": "EI_DEDUCTIONS",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-EI-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Federal Employment Insurance Deductions",
            "regexDescription": "Non-insurable Earnings Deductions",
            "helpText": "Amounts that are not included in insurable earnings, as described in the Canada.ca definition of pensionable and insurable earnings."
          }
        ],
        "country": "CA",
        "description": "Canada Employment Insurance Tax",
        "taxEffectiveDate": "2023-01-01",
        "isEmployerTax": false,
        "uniqueTaxID": "80-000-0000-EI-000",
        "provinceName": "Canadian Federal",
        "LCPRate": 0
      },
      {
        "rate": 0,
        "annual_max": 0,
        "isResident": true,
        "MaximumInsurable": 0,
        "max_contribution": 0,
        "v1Rate": 0,
        "provinceAbbreviation": "CAN",
        "AverageAssessmentRate": 0,
        "basicAmount": 15000,
        "max_contribution_period": 1,
        "provinceCode": "80",
        "LCPAmount": 750,
        "jurisdictionData": [
          {
            "regexType": "SingleValue",
            "parameterName": "FEDERAL_TOTAL_CLAIM_AMOUNT",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Form TD1, Line 13",
            "description": "Federal Total Claim Amount",
            "regexDescription": "Total Claim Amount",
            "helpText": "TC, 'Total claim amount' reported on federal Form TD1. If Form TD1 is not filed by the employee or pensioner, TC is the basic personal amount, and for non-resident individuals, TC is $0."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "BONUS_WITHHELD_AMT",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "1900-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127",
            "description": "Bonus Withheld Amount",
            "regexDescription": "Bonus Withheld Amount",
            "helpText": "Federal Bonus amount withheld. Bonus withheld amont is an optional parameter for employees who have bonus withheld amount with employer."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "FEDERAL_TAX_CREDIT",
            "provinceCode": "80",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor K3",
            "description": "Federal Tax Credit",
            "regexDescription": "Tax Credit",
            "helpText": "K3, Other provincial or territorial non-refundable tax credits (such as medical expenses and charitable donations) authorized by a tax services office or tax centre"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "PRESCRIBED_ZONE_AMOUNT",
            "provinceCode": "80",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Form TD1, Deduction for living in a prescribed zone",
            "description": "Federal Prescribed Zone Amount",
            "regexDescription": "Prescribed Zone Amount",
            "helpText": "HD, Annual deduction for living in a prescribed zone, as shown on Form TD1."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "PAY_PERIOD_INCOME_DEDUCTIONS",
            "provinceCode": "80",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor F2",
            "description": "Federal Pay Period Income Deductions",
            "regexDescription": "Pay Period Income Deductions",
            "helpText": "F2, Alimony or maintenance payments required by a legal document dated before May 1, 1997, to be payroll-deducted authorized by a tax services office or tax centre."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "APPROVED_SHARES",
            "provinceCode": "80",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, formula to calculate LCF",
            "description": "Federal Approved Shares",
            "regexDescription": "Approved Shares",
            "helpText": "The amount deducted or withheld during the year for the acquisition by the employee of approved shares of the capital stock of a prescribed labour-sponsored venture capital corporation."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "ANNUAL_INCOME_DEDUCTIONS",
            "provinceCode": "80",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor F1",
            "description": "Federal Annual Income Deductions",
            "regexDescription": "Annual Income Deductions",
            "helpText": "F1, Annual deductions such as child care expenses and support payments, requested by an employee or pensioner and authorized by a tax services office or tax centre"
          },
          {
            "regexType": "PickList",
            "parameterName": "OUTSIDE_CANADA",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "FALSE",
            "provinceAbbreviation": "CAN",
            "dataType": "Boolean",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^(TRUE|FALSE)$",
            "certificateLineNo": "Publication T4127, Outside Canada",
            "description": "Employee works outside Canada or in Canada beyond the limits of any province or territory",
            "regexDescription": "'True' or 'False'",
            "helpText": "Employee is outside Canada or in Canada beyond the limits of any province or territory."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "UNION_DUES",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor U1",
            "description": "Union Dues",
            "regexDescription": "Union dues for the pay period",
            "helpText": "U1, Union dues for the pay period paid to a trade union, an association of public servants, or dues required under the law of a province to a parity or advisory committee or similar body."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "PENSION_DEDUCTION",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor F",
            "description": "Pension and Saving Plan Deduction",
            "regexDescription": "Pension and Saving Plan Deduction for pay period",
            "helpText": "Pension and Saving Plan Deduction. Used to compute F and annual taxable income"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "PENSION_DEDUCTION_YTD",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0.0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor F4",
            "description": "Year-to-date Pension and Saving Plan Deduction",
            "regexDescription": "The year-to-date Pension and Saving Plan Deduction",
            "helpText": "Year-to-date Pension and Saving Plan Deduction. Used to compute Factor F4 and annual taxable income"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "PENSION_DEDUCTION_BONUS",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor F3",
            "description": "Pay Period Pension and Saving Plan Deduction for Bonus",
            "regexDescription": "Form TD1, Deduction for living in a prescribed zone",
            "helpText": "F3, Employee registered pension plan or registered retirement savings plan contributions deducted from the current non-periodic payment. You can use this field to apply other tax-deductible amounts to the non-periodic payment, such as union dues."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "RRSP_AMOUNT",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Pay Period Registered Retirement Saving Plan",
            "regexDescription": "Pay Period Registered Retirement Saving Plan",
            "helpText": "Pay Period Registered Retirement Saving Plan"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "RRSP_AMOUNT_YTD",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Year-to-date Registered Retirement Saving Plan",
            "regexDescription": "The year-to-date Registered Retirement Saving Plan ",
            "helpText": "The year-to-date Registered Retirement Saving Plan "
          },
          {
            "regexType": "SingleValue",
            "parameterName": "RPP_MP_AMOUNT",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Pay Period Registered Pension Plan for Money Purchase",
            "regexDescription": "Pay Period Registered Pension Plan for Money Purchase",
            "helpText": "Pay Period Registered Pension Plan for Money Purchase"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "RPP_MP_AMOUNT_YTD",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Year-to-date Registered Pension Plan for Money Purchase",
            "regexDescription": "The year-to-date Registered Pension Plan for Money Purchase",
            "helpText": "The year-to-date Registered Pension Plan for Money Purchase"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "DB_AMOUNT",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Pay Period Defined Benefit",
            "regexDescription": "Pay Period Defined Benefit",
            "helpText": "Pay Period Defined Benefit"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "DB_AMOUNT_YTD",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Year-to-date Defined Benefit",
            "regexDescription": "The year-to-date Defined Benefit",
            "helpText": "The year-to-date Defined Benefit"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "DPSP_AMOUNT",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Pay Period Deferred Profit Sharing Plan",
            "regexDescription": "Pay Period Deferred Profit Sharing Plan",
            "helpText": "Pay Period Deferred Profit Sharing Plan"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "DPSP_AMOUNT_YTD",
            "provinceCode": "80",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "CAN",
            "dataType": "Dollar",
            "uniqueTaxID": "80-000-0000-FIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "",
            "description": "Year-to-date Deferred Profit Sharing Plan ",
            "regexDescription": "The year-to-date Deferred Profit Sharing Plan ",
            "helpText": "The year-to-date Deferred Profit Sharing Plan "
          }
        ],
        "country": "CA",
        "description": "Canada Income Tax",
        "taxEffectiveDate": "2023-01-01",
        "isEmployerTax": false,
        "uniqueTaxID": "80-000-0000-FIT-000",
        "provinceName": "Canadian Federal",
        "LCPRate": 0.015
      },
      {
        "rate": 0,
        "annual_max": 0,
        "isResident": true,
        "MaximumInsurable": 0,
        "max_contribution": 0,
        "v1Rate": 0,
        "provinceAbbreviation": "BC",
        "AverageAssessmentRate": 0,
        "basicAmount": 11981,
        "max_contribution_period": 1,
        "provinceCode": "82",
        "LCPAmount": 0,
        "jurisdictionData": [
          {
            "regexType": "SingleValue",
            "parameterName": "PROVINCIAL_TAX_CREDIT",
            "provinceCode": "82",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "BC",
            "dataType": "Dollar",
            "uniqueTaxID": "82-000-0000-PIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor K3P",
            "description": "British Columbia Tax Credit",
            "regexDescription": "Tax Credit",
            "helpText": "K3P, Other provincial or territorial tax credits (such as medical expenses and charitable donations) authorized by a tax services office or tax centre"
          },
          {
            "regexType": "SingleValue",
            "parameterName": "APPROVED_SHARES",
            "provinceCode": "82",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "BC",
            "dataType": "Dollar",
            "uniqueTaxID": "82-000-0000-PIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, formula to calculate LCP",
            "description": "British Columbia Approved Shares",
            "regexDescription": "Approved Shares",
            "helpText": "The amount deducted or withheld during the year for the acquisition by the employee of approved shares of the capital stock of a prescribed labour-sponsored venture capital corporation."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "PROVINCIAL_ANNUAL_INCOME_DEDUCTIONS",
            "provinceCode": "82",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "BC",
            "dataType": "Dollar",
            "uniqueTaxID": "82-000-0000-PIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor F1",
            "description": "British Columbia Annual Income Deductions",
            "regexDescription": "Annual Income Deductions",
            "helpText": "F1, Annual deductions such as child care expenses and support payments, requested by an employee or pensioner and authorized by a tax services office or tax centre."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "PROVINCIAL_PAY_PERIOD_INCOME_DEDUCTIONS",
            "provinceCode": "82",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "BC",
            "dataType": "Dollar",
            "uniqueTaxID": "82-000-0000-PIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Publication T4127, Factor F2",
            "description": "British Columbia Pay Period Income Deductions",
            "regexDescription": "Pay Period Income Deductions",
            "helpText": "F2, Alimony or maintenance payments required by a legal document dated before May 1, 1997, to be payroll-deducted authorized by a tax services office or tax centre."
          },
          {
            "regexType": "SingleValue",
            "parameterName": "PRESCRIBED_ZONE_AMOUNT",
            "provinceCode": "82",
            "isOptional": false,
            "defaultValue": "0",
            "provinceAbbreviation": "BC",
            "dataType": "Dollar",
            "uniqueTaxID": "82-000-0000-PIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Form TD1, Deduction for living in a prescribed zone",
            "description": "British Columbia Prescribed Zone Amount",
            "regexDescription": "Prescribed Zone Amount",
            "helpText": "HD, Annual deduction for living in a prescribed zone, as shown on Form TD1. "
          },
          {
            "regexType": "SingleValue",
            "parameterName": "PROVINCIAL_TOTAL_CLAIM_AMOUNT",
            "provinceCode": "82",
            "isOptional": true,
            "defaultValue": "0",
            "provinceAbbreviation": "BC",
            "dataType": "Dollar",
            "uniqueTaxID": "82-000-0000-PIT-000",
            "taxEffectiveDate": "2020-01-01",
            "regex": "^([0-9]+([.][0-9]{0,2})?)$",
            "certificateLineNo": "Form TD1BC, Line 11",
            "description": "British Columbia Total Claim Amount",
            "regexDescription": "Total Claim Amount",
            "helpText": "TCP, 'Total claim amount' reported on the provincial or territorial Form TD1. If that form is not filed, TCP is the provincial or territorial basic personal amount."
          }
        ],
        "country": "CA",
        "description": "British Columbia Provincial Tax (PIT)",
        "taxEffectiveDate": "2023-01-01",
        "isEmployerTax": false,
        "uniqueTaxID": "82-000-0000-PIT-000",
        "provinceName": "British Columbia",
        "LCPRate": 0
      }
    ],
    "transactionStamp": {
      "failedTransactions": 0,
      "schemaVersion": "v2",
      "totalTransactions": 1,
      "calcDateTime": "2023-04-02T19:13:58Z",
      "steVersion": "2023-R4",
      "transactionType": "SetTaxList"
    },
    "errorStatus": {
      "errorCode": 0,
      "errorMessage": "No error"
    }
  }
}

SetTaxListResponse breakdown

Each object within the "taxItem" array represents a separate tax. Most of the properties returned with each tax are purely informational, but we'll need to know about the following ones for right now:

"uniqueTaxID"

The single most important field returned here. As mentioned in our introduction to basic concepts in the STE, these tax IDs are how you'll tell the STE which taxes you actually want calculated. Every tax in the Symmetry Tax Engine has a matching unique tax ID.

If you're a currently licensed STE client, please see Symmetry Unique Tax IDs in our Client Support Center for more information on how tax IDs are formatted and what each part of an ID represents.

"description"

The "user friendly" name of the tax.

"taxEffectiveDate"

The effective date of the most recent update to this tax, prior to the pay date that you input in your request. For example, if the engine already had a 2024 rate update for one of these taxes, it would still not return a 2024 effective date because we entered a 2023 pay date!

Like the input pay date, this will be in YYYY-MM-DD format.

"jurisdictionData"

You'll notice that some taxes were returned with an extra property that the other taxes don't have: "jurisdictionData".

This is returned when the tax will require you to know additional special information about the employee in order to calculate it properly. In the STE, these special elements are commonly referred to as miscellaneous parameters. There are normal parameters that are common to the setup of all taxes in the engine, while these miscellaneous parameters are unique to the specific taxes that they are attached to.

As before, there are several properties returned for each miscellaneous parameter, but we're only going to focus on the ones that we need right now. We'll use the following federal miscellaneous parameter output as an example for the following properties:

{
  "regexType": "SingleValue",
  "parameterName": "FEDERAL_TOTAL_CLAIM_AMOUNT",
  "provinceCode": "80",
  "isOptional": true,
  "defaultValue": "0",
  "provinceAbbreviation": "CAN",
  "dataType": "Dollar",
  "uniqueTaxID": "80-000-0000-FIT-000",
  "taxEffectiveDate": "2020-01-01",
  "regex": "^([0-9]+([.][0-9]{0,2})?)$",
  "certificateLineNo": "Form TD1, Line 13",
  "description": "Federal Total Claim Amount",
  "regexDescription": "Total Claim Amount",
  "helpText": "TC, 'Total claim amount' reported on federal Form TD1. If Form TD1 is not filed by the employee or pensioner, TC is the basic personal amount, and for non-resident individuals, TC is $0."
},
  • "parameterName": The engine's "official name" for the miscellaneous parameter — you can think of this like the ID of the parameter. When you go to set up the tax, you will need to enter this parameter name exactly as written!
    • In this example, the name is FEDERAL_TOTAL_CLAIM_AMOUNT.
  • "description": The "plain English" name of the parameter. For FEDERAL_TOTAL_CLAIM_AMOUNT, this is fittingly just "Federal Total Claim Amount."
  • "uniqueTaxID": A reference to the specific tax that this miscellaneous parameter belongs to.
    • "uniqueTaxID": "80-000-0000-FIT-000" indicates that FEDERAL_TOTAL_CLAIM_AMOUNT belongs to the federal income tax. This may appear obvious since it's included as part of the federal income tax object, but some taxes share parameter names. This allows you to easily keep track of which parameter goes with which tax.
  • "certificateLineNo": If this miscellaneous parameter correlates with a specific line on an employee's tax form, it will be listed here. For 2023, an employee's federal total claim amount comes from "Form TD1, Line 13." You can see the federal Form TD1 here.
  • "regex": This will return the regular expression that the STE uses to validate what you set the miscellaneous parameter to (when calculating taxes).
    • Since the federal total claim amount is a dollar amount, the engine will accept any number with up to two decimal places when setting FEDERAL_TOTAL_CLAIM_AMOUNT. Therefore, the regular expression returned is ^([0-9]+([.][0-9]{0,2})?)$.
    • Other common miscellaneous parameter regular expressions are Booleans (^(TRUE|FALSE)$), integers (^([0-9]+)$), and dates (^([12][0-9]{3}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01]))$), but there are many others as well!
  • "defaultValue": If you don't set this miscellaneous parameter (or if you set it to an invalid value), this is the default value that the engine will use instead.
    • For FEDERAL_TOTAL_CLAIM_AMOUNT, the default value is 0. Knowing an employee's total claim amount is critical to calculating their federal income tax correctly, so you'll want to make sure this is set!

Determining what information we need

Most miscellaneous parameters are only used for special scenarios, so for our first basic payroll calculation, we're only going to be using the following three:

  • FEDERAL_TOTAL_CLAIM_AMOUNT for the Canadian Federal Income Tax (80-000-0000-FIT-000)
  • PRESCRIBED_ZONE_AMOUNT for the Canadian Federal Income Tax (80-000-0000-FIT-000)
  • PROVINCIAL_TOTAL_CLAIM_AMOUNT for the British Columbia Provincial Tax (82-000-0000-PIT-000)

In order to correctly set these up, we'll need some info from the tax forms that Astrid filled out when she began her employment:

  • When Astrid filled out her 2023 federal Form TD1, she entered a total claim amount of $15,000 in Line 13 (in other words, she only claimed the basic personal amount of $15,000).
    • To represent this, we'll set FEDERAL_TOTAL_CLAIM_AMOUNT to 15000.
  • When Astrid filled out her 2023 federal Form TD1, she entered $0 for the "Deduction for living in a prescribed zone" on page 2.
    • To represent this, we'll set PRESCRIBED_ZONE_AMOUNT to 0.
  • Since Astrid works in British Columbia, she also filled out British Columbia Form TD1BC and entered $11,981 in line 11 for her total claim amount (the British Columbia basic personal amount).
    • To represent this, we'll set PROVINCIAL_TOTAL_CLAIM_AMOUNT to 11981.

👍

In summary, we now have a list of taxes to be calculated for Astrid, as well as a list of miscellaneous parameters that need to be set up in order to get accurate tax withholding amounts.

  • 80-000-0000-CPP-000 (Canada Pension Plan)
  • 80-000-0000-EI-000 (Canada Employment Insurance)
  • 80-000-0000-FIT-000 (Federal Income Tax)
  • 82-000-0000-PIT-000 (British Columbia Provincial Tax)

With all of this info, we can finally move onto calculating the taxes!

Updated 3 months ago

What’s Next

Next we'll calculate payroll taxes and determine Astrid's net pay!

Jump to top