KonaKart includes a powerful tax calculation system containing the following entities:
Zone: A physical area and is normally a state or region within a country.
Tax Area: An area defined for tax purposes and can be mapped to a zone or a country.
Tax Class: Defines a type of product for tax purposes because products within the same tax area may be taxed differently depending on their tax class. For example, children's clothes or basic necessities such as milk, may be taxed differently to luxury goods.
Tax Rate: A percentage number used to actually calculate the tax on a product. It has to be associated with a tax area and a tax class.
To start, you should define all of the zones for the country that you are interested in. Our database comes pre-populated with zones for a few countries. Even if the tax rate doesn't change between zones, it is still a good idea to populate them since this helps customers when entering addresses because they can be displayed in a drop down list.
Next, you should define the tax areas which may map directly to the zones. For example, the state of Texas may map directly to a tax area. Once you've defined all of you tax areas, you should map them to the zones using the Admin App.
The following step is to define the tax classes which are needed before entering any products. Once these are defined, the final step is to insert all of the tax rates that could be applied and map them with a tax area and a tax class.
If for some reason you need to look up the tax rate to be applied for a product from an external system, this rate can be applied to the order before saving it. In order to do this you must loop through all of the OrderProduct objects contained in the order and call the setTaxRate() method to set the tax rate. Once this has been done, you can call the getOrderTotals() engine call which re-calculates the order for the new tax rates.
In the US there are cases where a state contains multiple tax areas which may be determined by the zip code or a combination of zip code and county or some other details of the address. In this case, all of these physical zones may be added to the list of zones but made invisible so that when displaying the list of zones for a country, the list box does not show thousands of zones. For example, lets say that state ABC has 3000 different tax areas delimited by zip code. In this case all of these zones could be stored by KonaKart and all display the same name (i.e. state ABC). Therefore the zones table will contain 3001 zones for state ABC, 3000 of which are invisible and so are not returned by the getZonesPerCountry() API call. When registering, the customer selects the one visible zone called ABC and clicks the register button. Before calling the RegisterCustomer() API call, some custom code needs to call the searchForZones() API call with the zip code and state code as search criteria in order to get the correct zone. Once the correct zone has been fetched, the custom code must set the zone id in the CustomerRegistration object so that the registration uses that id. Note that the Zone object has a search field which must be set when inserting the zone to text that can be used to search for it (i.e. zip code in this example).
The procedure for handling the case when a customer is editing his address, is slightly different. In this case the customer may have registered with a zoneId that points to an invisible zone and so the zone is not present when a list is returned from the getZonesPerCountry() API call. Therefore, there needs to be custom code that retrieves the customer's zone using the searchForZones() API call and that removes the generic zone that describes the state so that the state does not appear twice. As in the RegisterCustomer() case, when the customer clicks the save button, the custom code must figure out the real zone of the customer using data within the address and populate the zoneId attribute of the address object before saving. The useZoneId attribute of the address object must also be set to true to stop the server code from attempting to determine the customer's zone.
Different countries and tax jurisdictions tend to define different ways of calculating tax. There are various ways of customizing KonaKart in order to make it compliant.
The configuration variable labeled "No of decimal places for currency" in the Configuration >> Admin App Configuration section of the Admin App allows you to set the precision of the price entry fields. Although your currency only uses two decimal places, you may want to enter net prices to more decimal places. If you are entering net prices but displaying prices after tax has been added (gross prices) you may need this extra precision in order to enable you to generate all gross prices. This can be set differently for each store in a multi-store environment. The precision defined by this variable is also the precision used for tax calculations.
The configuration variable labeled "Tax Quantity Rule" in the Configuration >> Stock and Orders section of the Admin App allows you to set the algorithm used for making the tax calculation. The actual code that calculates the tax is supplied in source code format under KonaKart/custom/utils/src/com/konakart/util and is called TaxUtils.java. As you can see from the code within TaxUtils.java there are currently two algorithms defined by the variables:
public static final int TAX_ON_TOTAL = 1
public static final int TAX_PER_ITEM = 2
The default TAX_ON_TOTAL algorithm calculates the total cost of an order line item by multiplying the unit price with the quantity and then calculates the tax. The TAX_PER_ITEM algorithm calculates and rounds the tax for a single item before multiplying the result by the quantity. The latter is useful in countries where the prices are displayed inclusive of tax and are calculated from the net price. Using this algorithm you are assured that the displayed price of an article remains consistent when the quantity bought is greater than 1.
If the current implementations defined within TaxUtils.java do not meet your requirements, you may customize this class and compile the modified code using the techniques defined elsewhere within this document.