Dev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Set the dual-rate tax calculator

Describes how to set up the dual-rate tax calculator in Optimizely Configured Commerce.

Optimizely Configured Commerce is capable of handling dual tax rates to support situations where two different taxes are assessed. This is evident in Canada, where provinces are required to calculate and display both the national tax and provincial tax throughout the site. In addition to calculating the taxes, the Dual Rate Tax Calculator will also calculate the Environmental Handling Fee (EHF), which is based on the province. Setting this up requires the use of the DualRate Tax Calculator and the Tax Code 2, Tax Rate 2, Tax Description, and Tax Description 2 fields.

General notes regarding behavior

General tax calculator

  • When the Dual Rate tax calculator is used, it calculates both rates against the order total and applies normal rounding rules to each result.
  • Tax details are stored within the Order History and Cart History. If any tax detail records exist, an Information icon will display. When clicked, a window is displayed containing the tax code, description, percentage, amount, and total tax.
  • The translations for Tax Code labels are done through the Translation Dictionary and are found under the Label source.

Environmental handling Fee (EHF)

The Environmental Handling Fee is a fee charged in Canada for certain electronic items and the fee itself is based on different criteria per province. Implementing this feature requires a few things be to set it up correctly:

  • Use the Dual Rate tax calculator
  • Set up custom properties for the Product table named EHF_XX where XX is the province code. Set up one property for each province you will need to collect the EHF for. They should all be number type controls.
  • Either through integration or manually, make sure to get the fee assigned to each qualifying product by province for the fee to be charged.

When the tax calculator is run, it will look to see if there are any custom properties with fee amounts in them for the EHF and then multiply that by the rate for the province the goods are being shipped to. This will be reflected internally as a tax detail record.

  • When the Dual Rate tax calculator is run, it will accumulate the fee defined in the EHF_XX record (XX = province code) per unit sold, which is then either creates a new record or updates the existing CustomerOrderTax record.

  • Any EHF calculated is added to the taxable total and the tax calculated on them

  • The EHF displays as if it is tax in terms of the Review & Pay page, Order Confirmation, Order Confirmation Email, and so on.

  • As is true of the Dual Rate tax calculator, the EHF description of "Environmental Handling Fees" is translatable using the Translation Dictionary found under the Label source.

Assign the tax calculator

To calculate multiple tax rates, change the system tax calculator to the DualRate calculator. When this calculator is run, it calculates both GST and PST against the order total, and rounds each result using standard rounding rules. If the calculation is exact, no rounding occurs.

Assign the tax calculator

  1. Go to Admin Console > Administration > System > Settings.
  2. Use the search box to search for the Tax Calculator setting.
  3. Select DualRate from the drop-down.
  4. Click Save.

Modify tax fields

Four tax fields need to be modified to include the GST and/or PST tax rates:

  • Tax Code 2
  • Tax Rate 2
  • Tax Description
  • Tax Description 2

Some of the tax fields listed above are hidden by default; however, a user assigned the role of ISC_System can expose them using the Application Dictionary. Use the steps below to modify the Application Dictionary:

Modify the application dictionary

  1. Go to Admin Console > Administration > System > Application Dictionary.

  2. In the Search box, enter State.

  3. Select the Properties finger tab.

  4. Enter the name of one of the fields listed above into the Search box.

  5. Click Edit.

  6. Click Yes for Can Edit

  7. Repeat these steps for each of the four fields.



    For more information on working with the Application Dictionary, see Application > Dictionary.

Modify the tax fields

  1. Go to Admin Console > Administration > Localization > Countries.

  2. Search or browse for Canada, and click Edit.

  3. Select the States finger tab.

  4. Click Edit next to a state record.

  5. Under the Tax Information header, fill in the appropriate tax code fields, including Tax Code 2, Tax Rate 2, Tax Description, and Tax Description 2.



    Tax Description and Tax Description 2 are displayed on the Review and Pay page, Order History page, and Invoice History page both on the commerce site and in the Admin Console. The description is captured with each order, so changes over time do not affect previous orders. Both the Tax Description and Tax Description 2 fields are translatable using the Translation Dictionary.

  6. Click Save.