Working with the improved taxation engine

Updated on 20-October-2016 at 10:16 AM

Business Catalyst End of life announcement - find out more details.

How to enable the improved taxation engine

The improved taxation engine is enabled for all New sites created after 27th of August 2012 by default.

For existing sites you can enable the improved taxation engine by taking the following steps.

  1. Log in to the admin of your site.
  2. Select E-Commerce > Shop Settings.
  3. Click the Enabled checkbox next to the New Taxation Engine option
  4. Click Save

Rounding formula comparison

Lets look at the previous rounding formula used verses the improved taxation engine.

Previous rounding formula: units * ROUND(unit price * (1 + tax_rate), 2)
Improved rounding formula: ROUND(units * unit price * (1 + tax_rate), 2)

Note: All rounding is to 2 decimal places.

Lets look at an example. If we have a product that costs $29.99, tax exclusive with a tax rate of 8.25%. A customer purchases 100 units.

The formulas used are as below:

Previous rounding formula: units * ROUND(unit price * (1 + tax_rate), 2) = 3246

Improved rounding formula: ROUND(units * unit price * (1 + tax_rate), 2) = 3246.42

Error compensation mechanism

To further reduce the errors in rounding calculation, Business Catalyst has introduced an error compensation/correction mechanism.

Example - A customer purchases 5 products, each with unit price 19.50 and a tax rate of 7.35%. Below is the error compensation method used:

Unit price Units Tax rate Unit Price tax (4 decimals) Tax in invoice Error
19.50 1 7.35 1.4333 1.43 0.0033
19.50 1 7.35 1.4333 + Err = 1.4366 1.44 -0.0033
19.50 1 7.35 1.4333 + Err = 14300 1.43 0.0000
19.50 1 7.35 1.4333 + Err = 1.4333 1.43 0.0033
19.50 1 7.35 1.4333 + Err = 1466 1.44 -0.0033
97.50 5 7.35 1.4333 7.17 -0.0033

Using the {tag_producttaxpercentage} with the improved taxation engine

When using the {tag_producttaxpercentage} with the improved tax engine, consider the below:
  • Add the tag_producttaxpercentage in the shopping cart, invoice and/or customer orders layouts, the parameter of this tag being the tax percentage (e.g. {tag_producttaxpercentage,10} for 10% tax)
  • When setting the product price do not associate any tax code with the product price (this should be the price with tax included)
  • tag_producttaxpercentage renders the value for total tax, considering the product quantity as well
  • When the layouts containing the {tag_producttaxpercentage} tag are rendered, the values rendered for the other available tags will consider the product price as tax inclusive. See below example for unit price tags for product price 10 (tax inclusive) and 10% tax
    • tag_productextaxamount: 9.09
    • tag_producttaxrate: 10%
    • tag_producttaxamount: 0.91
    • tag_productinctaxamount: 10

Output of order/invoice tags with the improved engine

There are changes to the output of some tags based on using the improved taxation engine. See example scenarios below:

Example scenario 1

Customer purchased the below on your site:

  • Example Product
  • Quantity: 10
  • Unit Price: 4.99
  • Tax Percentage: 8.16
  • Discount:0
  • No tax applied to shipping

Below is the output of tags based on the above scenario:

Shopping cart - Previous engine Shopping cart - Improved engine
giftvoucheramount:$0.00 giftvoucheramount:$0.00
invoicediscountamount:$0.00 invoicediscountamount:$0.00
invoicetotal:$61.00 invoicetotal:$60.97
invoicetotalextaxamount:$56.93 invoicetotalextaxamount:$56.90
invoicetotaltaxamount,BC,5,PST,GST:$4.07 invoicetotaltaxamount,BC,5,PST,GST:$4.07
orderid:108854 orderid:108867
productextaxamount:$4.99 productextaxamount:$4.99
productgrandtotal:$54.00 productgrandtotal:$53.97
productsubtotal:$49.93 productsubtotal:$49.90
producttaxamount:$0.41 producttaxamount:$0.41
producttaxpercentage,10:$4.07 producttaxrate:8.16%
producttaxrate:8.16% producttaxtotal:$4.07
producttaxtotal:$4.07 producttotal:$53.97
producttotal:$54.00 producttotalextax:$49.90
producttotalextax:$49.93 shippingextaxamount:$7.00
shippingextaxamount:$7.00 shippingtaxamount:$0.00
shippingtaxamount:$0.00 shippingtaxrate:$0.00
shippingtaxrate:0.000000 shippingtotal:$7.00
shippingtotal:$7.00
totaltaxpercentage,10,true,true:$4.07
Invoice - Previous engine Invoice - Improved engine
amountoutstanding:$0.00 amountoutstanding:$0.00
amountpaid:$61.00 amountpaid:$60.97
invoicetotal:$61.00 invoicetotal:$60.97
invoicetotalextaxamount:$56.93 invoicetotalextaxamount:$56.90
productextaxamount:$4.99 productextaxamount:$4.99
productgrandtotal:$54.00 productgrandtotal:$53.97
productinctaxamount:$5.40 productinctaxamount:$5.40
productsubtotal:$49.93 productsubtotal:$49.90
producttaxamount:$0.41 producttaxamount:$0.41
producttaxpercentage,10:$4.91 producttaxrate:8.16%
producttaxrate:8.16% producttaxtotal:$4.07
producttaxtotal:$4.07 producttotal:$53.97
producttotal:$54.00 producttotalextax:$49.90
producttotalextax:$49.93 shippingextaxamount:$7.00
shippingextaxamount:$7.00 shippingtaxrate:$0.00
shippingtaxrate:0.000000% shippingtotal:$7.00
shippingtotal:$7.00
totaltaxpercentage,10:$5.55
Customer order (Layouts and secure zones) - Previous engine Customer order (Layouts and secure zones) - Improved engine
amountoutstanding:$0.00 amountoutstanding:$0.00
amountoutstandingactual: $0.00 amountoutstandingactual: $0.00
amountoutstandingactual:$0.00 amountoutstandingactual:$0.00
amountpaid:$61.00 amountpaid:$60.97
amountpaidactual:$61.00 amountpaidactual:$60.97
invoicetotal:$61.00 invoicetotal:$60.97
invoicetotaltaxamount:$4.07 invoicetotaltaxamount:$4.07
productextaxamount:$4.99 productextaxamount:$4.99
productgrandtotal:$54.00 productgrandtotal:$53.97
productinctaxamount:$5.40 productinctaxamount:$5.40
productsubtotal:$49.93 productsubtotal:$49.90
producttaxamount:$0.41 producttaxamount:$0.41
producttaxrate:8.16% producttaxrate:8.16%
producttaxtotal:$4.07 producttaxtotal:$4.07
producttotal:$54.00 producttotal:$53.97
shippingextaxamount:$7.00 shippingextaxamount:$7.00
shippingtaxamount:$0.00 shippingtaxamount:$0.00
shippingtaxrate:0.000000% shippingtaxrate:$0.00
shippingtotal:$7.00 shippingtotal:$7.00

Example scenario 2

Customer purchased the below on your site:
  • Example Product 2
  • Quantity: 5
  • Unit Price: 29.99
  • Tax Percentage: 0
  • Discount: 58% (user discount per catalog/wholesaler)
  • No tax applied to shipping
Below is the output of tags based on the above scenario:
Shopping cart - Previous engine Shopping cart - Improved engine
giftvoucheramount:$0.00 giftvoucheramount:$0.00
invoicediscountamount:$0.00 invoicediscountamount:$0.00
invoicetotal:$63.00 invoicetotal:$62.98
invoicetotalextaxamount:$63.00 invoicetotalextaxamount:$62.98
invoicetotaltaxamount,BC,5,PST,GST:$0.00 invoicetotaltaxamount,BC,5,PST,GST:$0.00
orderid:108855 orderid:108871
productextaxamount:$12.60 productextaxamount:$12.60
productgrandtotal:$63.00 productgrandtotal:$62.98
productsubtotal:$63.00 productsubtotal:$62.98
producttaxamount:$0.00 producttaxamount:$0.00
producttaxpercentage,10:$4.75 producttaxrate:0%
producttaxrate:0% producttaxtotal:$0.00
producttaxtotal:$0.00 producttotal:$62.98
producttotal:$63.00 producttotalextax:$62.98
producttotalextax:$63.00 shippingextaxamount:$0.00
shippingextaxamount:$0.00 shippingtaxamount:$0.00
shippingtaxamount:$0.00 shippingtaxrate:$0.00
shippingtaxrate:0.000000 shippingtotal:$0.00
shippingtotal:$0.00
totaltaxpercentage,10,true,true:$4.75
Invoice - Previous engine Invoice - Improved engine
amountoutstanding:$0.00 amountoutstanding:$0.00
amountpaid:$63.00 amountpaid:$62.98
invoicetotal:$63.00 invoicetotal:$62.98
invoicetotalextaxamount:$63.00 invoicetotalextaxamount:$62.98
productextaxamount:$12.60 productextaxamount:$12.60
productgrandtotal:$63.00 productgrandtotal:$62.98
productinctaxamount:$12.60 productinctaxamount:$12.60
productsubtotal:$63.00 productsubtotal:$62.98
producttaxamount:$0.00 producttaxamount:$0.00
producttaxpercentage,10:$5.73 producttaxrate:0%
producttaxrate:0% producttaxtotal:$0.00
producttaxtotal:$0.00 producttotal:$62.98
producttotal:$63.00 producttotalextax:$62.98
producttotalextax:$63.00 shippingextaxamount:$0.00
shippingextaxamount:$0.00 shippingtaxrate:$0.00
shippingtaxrate:0.000000% shippingtotal:$0.00
shippingtotal:$0.00
totaltaxpercentage,10:$5.73
Customer order (Layouts and secure zones) - Previous engine Customer order (Layouts and secure zones) - Improved engine
amountoutstanding:$0.00 amountoutstanding:$0.00
amountoutstandingactual: $0.00 amountoutstandingactual: $0.00
amountoutstandingactual:$0.00 amountoutstandingactual:$0.00
amountpaid:$63.00 amountpaid:$62.98
amountpaidactual:$63.00 amountpaidactual:$62.98
invoicetotal:$63.00 invoicetotal:$62.98
invoicetotaltaxamount:$0.00 invoicetotaltaxamount:$0.00
productextaxamount:$12.60 productextaxamount:$12.60
productgrandtotal:$63.00 productgrandtotal:$62.98
productinctaxamount:$12.60 productinctaxamount:$12.60
productsubtotal:$63.00 productsubtotal:$62.98
producttaxamount:$0.00 producttaxamount:$0.00
producttaxrate:0% producttaxrate:0%
producttaxtotal:$0.00 producttaxtotal:$0.00
producttotal:$63.00 producttotal:$62.98
shippingextaxamount:$0.00 shippingextaxamount:$0.00
shippingtaxamount:$0.00 shippingtaxamount:$0.00
shippingtaxrate:0.000000% shippingtaxrate:$0.00
shippingtotal:$0.00 shippingtotal:$0.00