How to use the Discount Coupon Codes Module

Contents:

• Configuring the Order Total Module
• Creating Discount Coupon Codes
  • Explanation of Coupon Fields
• How to create percentage discounts
• How to create fixed discounts
• Common Problems
• Support

Configuring the Order Total Module

To configure the Discount Coupon Codes module, go to Modules > Order Total > Discount Coupon in the admininistration section of your website. Click the Edit button on the right side of the screen to edit the configuration options. Explanations for each option are provided below:

• Display Discount Coupon
  Set this option to true to use the discount coupons module. If it is set to false, the Discount Coupon Code box will not appear on the checkout payment page.
• Sort Order
  Set this to a UNIQUE value. Each order total module must have a unique sort order, or they will not display correctly.
• Display Discount with Minus (-) Sign
  Set this option to true to have the discount display with a minus sign in the order confirmation, invoice, etc. If this is set to false, the discount line will simply display the discount amount.
• Display Subtotal with Applied Discount
  Set this option to true to display the order subtotal with the discount applied. If this option is set to true, you will want to set the sort order for the discount coupons so that it displays before the order subtotal line, like so:
  

  Item Doodle x 1:	$25.00
  Discount Coupon XYZ Applied:	-$5.00
  Subtotal:	$20.00
  Tax:	$1.39
  Total:	$21.39

  If this option is set to false, the discount will not be applied to the order subtotal. In this case, you will want to set the sort order for the discount coupons so that it displays after the order subtotal line:
  

  Item Doodle x 1:	$25.00
  Subtotal:	$25.00
  Discount Coupon XYZ Applied:	-$5.00
  Tax:	$1.39
  Total:	$21.39

  
  PLEASE NOTE: If you have prices set to display with taxes, then the order subtotal will always be displayed with the discount applied.
• Random Code Length
  If you do not provide a code when creating a coupon, the discount coupons module will create a random string of letters and numbers for you. This setting controls the length of randomly generated codes.
• Display Discount Total Lines for Each Tax Group?
  Discount coupons are applied to each item separately, in order to properly calculate tax if there are multiple tax groups (local and state taxes, for example). Set this to true to display the discount applied to each tax group. Set this to false to combine the discount and display as one order total line.
• Use the language file to format display string?
  When you have multiple languages and want the order total line for the discount to appear in the language selected by the customer, you will need to set this option to true and edit the includes/languages/your_language/modules/order_total/ot_discount_coupon.php file. If you use only one language, you can set this to false and use the Display Format for Order Total Line configuration field to format the order total line. If this field is set to true, then the value in the Display Format for Order Total Line configuration field will be ignored.
• Display Format for Order Total Line
  Use this setting to change how the discount coupons order total line is formatted and displayed. You can insert the variables to display dynamic data, such as the coupon code used or the discount percent. The list of available variables:
  [code]
  [coupon_desc]
  [percent_discount]
  [min_order]
  [number_available]
  [tax_desc]

Creating Discount Coupon Codes

Log in to your admin section and go to Catalog > Discount Coupons. Click the New Coupon button to create a new Discount Coupon Code. The only field that is required is the percent discount field.

Once you have created a discount coupon code, you may distribute it in any format. The only information a customer will need to use a coupon is the code you specified when creating the coupon. You can send out codes in newsletters, order confirmations, etc.

Discounts are displayed as order total lines in the customer's checkout confirmation screen and order history screen, and in all admin order screens.

Discounts are applied BEFORE tax.

Explanation of Coupon Fields:

• Coupon Code
  This is the code you will give to customers which they enter during the checkout process. It can be any alphanumeric character, up to 32 characters long. If you leave this field blank, a randomn alphanumeric code will be generated for you. This field cannot be edited for existing coupons.
• Description
  This is a short description field to help you administer your coupons. The contents of this field are not displayed to the customer unless you choose to display it in the order total format. See "Display Format for the Order Total Line" in Configuring the Order Total Module.
• Discount Percent
  The percentage discount to apply to the order. Enter this as a decimal amount, eg .15 rather than 15 or 15%. This field cannot be edited for existing coupons.
• Fixed Discount
  You may enter a fixed discount amount instead of a percentage discount along with an order minimum to have the module calculate the proper percentage discount to acheive the given fixed discount amount. Enter the fixed discount amount without any currency marks, eg 5 instead of $5. Leave this blank to use a simple percentage discount. This field cannot be edited for existing coupons.
• Start Date
  Enter a start date if you wish to limit the when customers may begin using this coupon. You may leave this field empty to allow customers to use the coupon as soon as it is created.
• End Date
  Enter an ending date if you wish to limit how long customers may use this coupon. You may leave this field empty to allow customers to use the coupon as long as they wish.
• Max Use
  Enter the maximum number of times each individual customer may use this coupon. If you do not enter a value, or you enter 0, the customer will be allowed to use this coupon an unlimited number of times.
• Min Order
  Enter the minimum order subtotal a customer must have before he or she may use this coupon. If you do not enter a value, or you enter 0, there will be no order minimum required for this coupon. This field cannot be edited for existing coupons.
• Max Order
  Enter the maximum order subtotal to which this discount should be applied. You may use this field to set an upper limit on discounts. If an order subtotal is greater than the Max Order field, then the Max Order field will be used as the basis for calculating the discount. If you do not enter a value, or you enter 0, the discount will be applied to the entire order subtotal amount. This field cannot be edited for existing coupons.
• Number Available
  Enter the global number of coupons available. You may use this to limit the number of times the coupon can be used for the entire store. This may be used to give a discount to the first 200 customers on a particular day, for example.

How to Create Percentage Discounts

Percentage discounts require only a code and a discount percentage. All other fields are optional.

How to Create Fixed Discounts

PLEASE NOTE: Due to the way osCommerce handles order total calculation and the way that Discount Coupon Codes applies a discount to order totals, fixed discounts have the possibility of being off by small fractions. This can possibly result in a fixed discount of $5.00 being displayed in the order total line as $4.99, for example. The frequency of this happening will be very low. The reason has to do with when the Discount Coupon Codes contribution calculates discounts. The calculation happens during the order object creation, when final total values are not yet known, so the discount is applied incrementally. There are pros and cons to this method. Some other Discount Coupon modules calculate discounts after the order object has been created and so may handle fixed discounts with a higher degree of accuracy. If the possibility of fractional rounding errors is unacceptable to you or your customers, I recommend trying one of the other discount coupon contributions.

Fixed discounts are created by setting an order minimum (the minimum amount a customer must have in his or her cart before being eligeable for the discount), a percentage discount, and an order maximum (the maximum order amount to apply the discount to). If the order maximum is the same as the order minimum, then the percentage discount for every order using this code will be fixed.

Suppose you wish to allow a $5.00 discount on orders $25 or more. By setting the order minimum and maximum both to $25, you ensure the applied discount will be the same for all orders using this discount coupon code. If the discount percent is 20%, the discount will always be $5.00.

You may enter an order minimum and a fixed discount amount when creating coupons to have the Discount Coupon Codes module automatically calculate the correct discount percentage for you.

Common Problems

• Discount coupon does not display in order subtotal during checkout
  confirmation.
  Ensure the discount coupon has a unique sort order. Set this in
  Modules > Order Total.
• Warning: include(***file1***) [function.include]: failed to open stream: No
  such file or directory in ***file2*** on line ***line#***
  Ensure that you have uploaded ***file1*** to the correct directory.
• "Discount Coupon" does not appear in the list of Order Total modules under
  Modules > Order Total in the admin section.
  Ensure that you have uploaded the module files contained in the contribution
  package:
  catalog/includes/modules/order_total/ot_discount_coupon.php
  catalog/includes/languages/english/modules/order_total/ot_discount_coupon.php
• The Discount Applied order total line shows an incorrect discount amount for
  the order subtotal. (Only happens on some orders and amount is off by no more
  than a few cents.)
  There isn't really one. The discount is applied before tax, and OSC allows
  for multiple tax groups in each order. This means the discount percentage
  must be applied to each line item in the order, taking into account the tax
  rate for that item. Rounding can then cause the Discount Applied line to be a
  few cents off of the actual discount percentage for the Sub-Total line.
  
  The discount is not actually taken from the order Sub-Total, even though it
  may appear as though it is. If you have configured your store to display
  prices with taxes and/or you have configured your Discount Coupon Codes module to
  display the order Sub-total without the discount applied, then your likelihood
  of running into this situation is slightly higher.
• Fatal error: Cannot redeclare class discount_coupon in ***path to shop***/includes/classes/discount_coupon.php on line 14.
  Edit the file includes/classes/discount_coupon.php and comment out the line
  require_once( DIR_FS_CATALOG.DIR_WS_CLASSES.'discount_coupon.php' );

Support

You can find support for this contribution at http://forums.oscommerce.com/index.php?showtopic=213019 (OSCommerce User Forums). Please read through the previous postings to see if your problem or question has already been answered.