Version: 2.2
Release: Apr 11, 2006
Compatibility: QC v1.0+
Languages: en
Author: Wizzud
Contact: rb@wizzud.com

Tax And Discount

Plugin module for Quick.Cart by OpenSolution.org

Synopsis

This plugin offers ...
  • The ability to apply a tax on orders
  • Discounts, at Basket level (not Product level)
  • Banded discounts based on total value of Basket or number of items in Basket
  • Discounts as a percentage or as an amount
  • Options to tax delivery charges, and to exclude tax from total (ie. where product prices already include a tax element)
  • Option to provide a pre-tax sub-total NEW!
  • Simplified installation and maintenance*
* Please note the Prerequisites for running this plugin. Due to the complexity of the interaction with the core Quick.Cart code it is necessary to use the facilities provided by the Plugin Manager. If this causes any problems I apologise in advance, but it is unavoidable.

Compatibility

Quick.Cart versions prior to v1.0 : Not compatible.
Quick.Cart versions 1.0 upward : Compatible at the time of writing.
Other Plugins : At the time of release, this plugin is known to be compatible with the following available plugins (other than those listed as Prerequisite):
  • productsInRow v1.1
  • productAttributes v2.0
  • htmlMailOrderDetails v2.0
Any other plugins not mentioned above may or may not work in conjunction with Tax And Discount, but it is always worth checking their available documentation to see if they specify compatibility with this plugin.
Top of Page

Prerequisites

Plugin Manager v2.0+ : Uses the Plugin Manager's 'extendTplParser' class extension.
None other, assuming that the Compatibility requirements have been met.
Top of Page

Upgrade

There is an upgrade path starting with version 2.0 of this plugin. Lower versions are not upgradable.
Top of Page

Upgrading v2.1 to v2.2

The only files that have changed are
  • /plugins/taxAndDiscount/tax.php
  • /plugins/taxAndDiscount/setup.php
so you can, if you wish, simply unzip the v2.2 release file, find these 2 files, and overwrite the v2.1 versions with the updates. Then you only need to complete step (b) below; otherwise, you should follow the full upgrade instructions below.
Top of Page

Upgrading v2.0/v2.1 to v2.2

I suggest you take a screen dump of your current Tax And Discount plugin's configuration page before upgrading, so that you can re-apply any changes you may have made from the default configuration.
  1. Follow steps 1, 2 and 3 of the Installation instructions below, replacing old files/folders with the new versions.
  2. Go to the Configuration - Plugins option on the Admin menu. You will see a warning that the Tax And Discount plugin version number has changed. If Plugin Manager has been configured for Version Checking then the plugin will also have been disabled and the Configuration button greyed out.
    • Click the Reload Setup button for the Tax And Discount plugin
    • Click the Configuration button for the Tax And Discount plugin, make any changes necessary, and Save
    • Re-enable the plugin, and Save
For anyone upgrading from earlier versions of Quick.Cart, the extra fields generated by this plugin used to be held in the db/orders.php file, but have been moved to the db/orders_ext.php file since QCv1.0. Conversion routines are available for standard QC upgrades from pre version 1.0 Quick.Cart, but these will not suffice for upgrading to this new version of the Tax And Discount plugin - new fields have been introduced which were not required/available in previous versions. The only solution I can recommend is that you archive and then clear down your existing orders and start from a clean database. In fact, to prevent possible record layout problems due to Quick.Cart's upgraded file handling routines, I advise that this clear down be performed regardless when installing this plugin.
Top of Page

Install

Where possible, the release folder is laid out in the correct folder structure to aid installation.
  1. Copy the entire taxAndDiscount folder from the release/plugins/ folder into your Quick.Cart plugins/ folder.
  2. Copy the contents of the release/templates/admin/ folder to your Quick.Cart templates/admin/ folder (1 new file: taxAndDiscount.tpl).
  3. Copy the contents of the release/templates/ folder to your Quick.Cart templates/ folder (1 new file: taxAndDiscount.tpl, NOT the Admin folder!).
  4. Go to the Configuration - Plugins option on the Admin menu, and configure and then enable the taxAndDiscount plugin.
Top of Page

User Guide

Top of Page

Configuration

The plugin's configuration parameters are accessible via the Plugin Manager, and full explanations have been provided for each and every setting. Please read them carefully!
One thing that should be pointed out is that you can enable/disable both tax and/or discount via the configuration settings, and that once the plugin has been installed and been in use, then these settings should be used to control it in preference to disabling the entire plugin. The reason for this is that the extra fields will still be maintained on the db/orders_ext.php file, which will keep the record layouts compatible between orders entered with or without tax and/or discounts being enabled.
Top of Page

Discount Rates

The on/off switches and tax rate are fairly self-explanatory, but the discount rates may require a bit of clarification.
The discount rates consist of an array of sub-arrays. Each sub-array consists of 4 values:
  • the trigger amount at which the discount becomes applicable
  • the minimum number of items that must be present in the basket for the discount to apply
  • the discount
  • whether the discount is an amount or a percentage
The sub-arrays must be presented in ascending order, primarily of the trigger amounts, and within them the trigger items, or you will end up with the wrong discount being applied!
Only the discount for the highest applicable trigger amount/trigger items is applied, and only the basket contents total is used to determine which trigger amount is applicable, ie. delivery charges are not included or discounted. The number of items in the basket can range from multiple quantities of a single product, to single qauntities of multiple products - all count.
Discount rates are positive; the calculated amount of discount is presented as negative and therefore subtracted from the total. [A negative discount rate would become a surcharge and be added to the total!]
Top of Page

Example - Simple

"UK-base trading; product prices and delivery charges are exclusive of VAT; orders of £200 or more receive a 10% discount, and orders of £100 - £200 receive a 5% discount; customers should be able to see the discount rate they are getting".
  • Enable Tax
  • Enable Discount
  • Tax Rate : 17.5
  • Tax Delivery Cost - enabled
  • Include Tax In Total - enabled
  • Display Tax As Absolute - disabled
  • SubTotal Excluding Tax - disabled
  • Show Discount Rate - enabled
  • Discount Rates :
    • array(100, 0, 5, '%'),
    • array(200, 0, 10, '%')
Top of Page

Example - Complex

"Tax rate is 15%; product prices are quoted before tax, but delivery charges are quoted externally and include tax; all products ordered online should have a discount of 2%, with an additional 2% for every £100 spent up to a maximum discount of 12%; any order of 10 items or more gets an (additional) 3% regardless of amount; customer does not need to see the actual discount rate applied".
  • Enable Tax
  • Enable Discount
  • Tax Rate : 15
  • Tax Delivery Cost - disabled
  • Include Tax In Total - enabled
  • Display Tax As Absolute - disabled
  • SubTotal Excluding Tax - disabled
  • Show Discount Rate - disabled
  • Discount Rates :
    • array(0, 0, 2, '%'),
    • array(0, 10, 5, '%'),
    • array(100, 0, 4, '%'),
    • array(100, 10, 7, '%'),
    • array(200, 0, 6, '%'),
    • array(200, 10, 9, '%'),
    • array(300, 0, 8, '%'),
    • array(300, 10, 11, '%'),
    • array(400, 0, 10, '%'),
    • array(400, 10, 13, '%'),
    • array(500, 0, 12, '%'),
    • array(500, 10, 15, '%')
Top of Page

Example - Amounts

"Tax rate is 15%; product prices are quoted before tax, but delivery charges are quoted externally and include tax; all products are priced at £5 and every tenth item ordered is free, up to a maximum of 5 free items; additionally, any spend over £100 gets a 5% discount, over £200 gets 10%; oh, and I'd like to see a pre-tax sub-total".
  • Enable Tax
  • Enable Discount
  • Tax Rate : 15
  • Tax Delivery Cost - disabled
  • Include Tax In Total - enabled
  • Display Tax As Absolute - disabled
  • SubTotal Excluding Tax - enabled
  • Show Discount Rate - disabled
  • Discount Rates :
    • array(0, 10, 5, 'a'),
    • array(0, 20, 5, 'a'),
    • array(0, 30, 5, 'a'),
    • array(0, 40, 5, 'a'),
    • array(0, 50, 5, 'a'),
    • array(100, 0, 5, '%'),
    • array(200, 0, 10, '%')
Top of Page

Example - No Tax

"All product prices and delivery charges already include tax and there is no need to show how much tax is being charged; all products get a 15% discount on more than 3 items, which the customer should see to encourage him to re-order."
  • Disable Tax
  • Enable Discount
  • Tax Rate : irrelevant
  • Tax Delivery Cost - irrelevant
  • Include Tax In Total - irrelevant
  • Display Tax As Absolute - irrelevant
  • SubTotal Excluding Tax - irrelevant
  • Show Discount Rate - enabled
  • Discount Rates :
    • array(0, 4, 15, '%')
Top of Page

Example - No Discount

"Tax rate is 14%; product prices and delivery charges already include tax but law requires that the customer be told how much tax is being charged (as a positive amount), and that a pre-tax sub-total is displayed; product prices already include any discounts."
  • Enable Tax
  • Disable Discount
  • Tax Rate : -12.281
  • Tax Delivery Cost - enabled
  • Include Tax In Total - disabled
  • Display Tax As Absolute - enabled
  • SubTotal Excluding Tax - enabled
  • Show Discount Rate - irrelevant
  • Discount Rates : irrelevant
NOTE: The tax rate has been set to (negative) 14/114 to get the 14% tax that has been included in all prices.
Top of Page

Example - Tax Rebate

[I'm not sure that this is a valid real-life scenario, but ...]
"The local tax rate is 22%, and all product prices and delivery charges have to be quoted inclusive of tax; however all my online customers are entitled to a tax rebate on the products themselves; I can also offer discounts for large orders: 4% on orders over $500, 7% on orders over $1000, and a flat 10% where they order more than 50 items."
  • Enable Tax
  • Enable Discount
  • Tax Rate : -18.033
  • Tax Delivery Cost - disabled
  • Include Tax In Total - enabled
  • Display Tax As Absolute - disabled
  • SubTotal Excluding Tax - disabled
  • Show Discount Rate - enabled
  • Discount Rates :
    • array(610.01, 0, 4, '%'),
    • array(610.01, 51, 10, '%'),
    • array(1220.01, 0, 7, '%'),
    • array(1220.01, 51, 10, '%')
NOTE: The tax_rate is -22/122, excludes delivery, displays as negative, and IS included in the total (ie. subtracted from). Also, because discount is calculated BEFORE tax, the trigger amounts in the discount_rates have been modified to include the tax that will be rebated; and they only come into effect for amounts GREATER THAN $500 or $1000!
Top of Page

Language

By default this plugin is only supplied with an English language file - /plugins/taxAndDiscount/lang-en.php.
If you wish to provide translations for your own language, copy lang-en.php to lang-[2-char-code].php (within the same folder), where [2-char-code] is the recognised code for your language. For example, a Polish language file would be /plugins/taxAndDiscount/lang-pl.php.
The plugin will automatically load the English file first, and then look for the language file in the Shop's configured language, so that the English text is always there as a backup.
Top of Page

Change Log

Version 2.2

  • Code : BugFix - tweaked tax.php so that the tax amount is displayed when it should be, and is not dependent on the 'subtotalExTax' configuration setting!
  • Documentation : updated for v2.2 upgrade instructions.

Version 2.1

  • Code : updated tax.php functions to handle pre-tax sub-total field.
  • Javascript : update pre-tax sub-total if present on orders delivery page.
  • Template files : added blocks for pre-tax sub-totals - screen and print, shop and admin.
  • Configuration : added new boolean for pre-tax sub-total, with appropriate language file updates.
  • Stored fields : orders_ext.php now also stores the settings (at the time the order is placed) for 'Display Tax As Absolute' and 'SubTotal Excluding Tax', for more accurate re-creation of the order from Admin.
  • Setup : upped version number.
  • Documentation : corrected 'Example - No Discount'; corrected style to properly show highlight; updated whole document to include pre-tax sub-total field.
  • General : tidied up unnecessary (old) commented out code; removed tax-admin.php (not used)
Top of Page
~~ The End ~~