## How to use the Discount Coupon Codes Module

### Contents:

- Configuring the Order Total Module
- Creating Discount Coupon Codes
  - Explanation of Coupon Fields

- Exclusions

- 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:

- Enable 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

- Exclude product specials?
  If this is set to true, discounts will not be applied to products currently on special.
- Random Code Length
  When you choose to create a new 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. If you only use one tax class, this setting is ignored. If you have multiple tax classes, you will want to consider how you wish them to display. For example, this is how the confirmation page, confirmation email, and invoice would appear for an order with multiple tax classes and this setting is set to true:

  Subtotal: | $25.00
  Discount Coupon XYZ Applied (State tax): | -$2.30
  Discount Coupon XYZ Applied (Local tax): | -$2.70
  Tax: | $1.39
  Total: | $21.39

  And this is how the same order would appear when this setting is set to false:

  Subtotal: | $25.00
  Discount Coupon XYZ Applied: | -$5.00
  Tax: | $1.39
  Total: | $21.39

- Allow negative order total?
  Set this to false to prevent order totals from being negative. This can happen if you create a fixed discount coupon with no price minimum.
- 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 on the checkout confirmation page, the confirmation email, and invoice. You can insert the variables to display dynamic data, such as the coupon code used or the discount percent. For example, a display format of "Discount Coupon [code] for [discount_amount] applied" would display invoice as:

  Subtotal: | $25.00
  Discount Coupon XYZ for 20% Applied: | -$5.00
  Tax: | $1.39
  Total: | $21.39

  The list of available variables:
  - [code]
  - [coupon_desc]
  - [discount_amount]
  - [min_order]
  - [number_available]
  - [tax_desc]
- Debug Mode
  Set this to true to print out some helpful debugging information on checkout_confirmation.php. To view the debug info, View Source in your browser. The debug info is printed inside the "<!-- Discount Coupons DEBUG" and "End Discount Coupons DEBUG-->" HTML comment tags at the top of that file.

Please Note: When Debug Mode is "on" (set to true), error messages will not work - the user will not be redirected to the payment screen when there is an error.

### 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 discount amount.

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 consist of any alphanumeric characters, up to 32 characters long. If you leave this field blank, a random alphanumeric code will be generated for you. See Random Code Length in Configuring the Order Total Module to edit the length of random codes generated. 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 Amount
  The discount amount to apply to the order.

  - For percentage discounts, enter the amount as a decimal. For example, .15 instead of 15 or 15% for a discount of 15%
  - For fixed discounts, enter the amount exactly as you want it to appear. For example, 10 for a $10 discount
  - For shipping discounts, enter the percentage discount you wish to offer. For example, 1 for free shipping, .5 for 50% off shipping

- Discount Type
  Select the type of discount this is. Make sure that your discount amount is in the proper format for the discount type you have chosen.
- 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.

  Start dates and end dates must be in the same format as the formatting specified in admin/includes/languages/english.php (or the appropriate main language file for the language of your admin section).

- 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.
- Min Order Type
  Select the type of minimum order restriction you'd like to use. If you select Price Total, the minimum order total required for a customer to use the coupon will be the value entered in the Min Order field. If you select Product Quantity, the minimum number of items required for a customer to use the coupon will be the value entered in the Min Order field.
- 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.

#### Exclusions

You have the ability to manage excluded products, categories, manufacturers, customers, and shipping zones for each coupon you create. Customers will not be notified a product is excluded unless the order total/product quantity of non-excluded items doesn't meet the Min Order requirement for the coupon. In that case, they will not be given notice which particular items are excluded. If you create coupons with exclusions, it is recommended to ensure the customers know up front which products are excluded to avoid confusion.

You must create a coupon before you can manage exclusions for that coupon. See the section on Creating Discount Coupon Codes for help.

Log in to your admin section and go to Catalog > Discount Coupons. Select the coupon for which you wish to manage exclusions. In the box on the right side of the screen, you will see six buttons: edit, delete, product exclusions, manufacturer exclusions, category exclusions, customer exclusions, and shipping zone exclusions. Click on the button for the type of exclusions you wish to create.

The four exclusions screens work similarly. The box on the left will list products/manufacturers/categories/customers for which the coupon is NOT excluded. The box on the right lists products/manufacturers/categories/customers for which the coupon IS excluded. Use the top four buttons between these two boxes to move products from one box to the other. Click save when you are done.

If a product is in any excluded category, it will be considered an excluded item. For example, Product A is in Category 1 and Category 2. Category 1 is an excluded category. Even if a customer sees Product A in Category 2 and adds it to his/her cart, the product will still be considered excluded because Category 1 is excluded.

You may edit the fields that are displayed in the exclusions boxes by editing the following code starting on line 17 in admin/coupons_exclusions.php:

      /**********************************************/
      //toggle these true/false to determine which fields to display in product list in the same order as they are listed below

      $display_fields = array(
                              'categories' => array( 'c.categories_id' => false,
                                                     'cd.categories_name' => true ),

                              'customers' => array( 'c.customers_id' => false,
                                                    'CONCAT( c.customers_firstname, CONCAT( " ", c.customers_lastname ) ) AS name' => true,
                                                    'c.customers_email_address' => false ),

                              'manufacturers' => array( 'm.manufacturers_id' => false,
                                                        //'mi.manufacturers_url' => false,
                                                        'm.manufacturers_name' => true ),

                              'products' => array( 'p.products_id' => false,
                                                   'p.products_model' => false,
                                                   'pd.products_name' => true,
                                                   'p.products_price' => false ) );

      //separator for the fields in the listing
      $separator = ' :: ';

      //category exclusions
      //separator for the category names
      $category_separator = '->';
      //toggle true/false to determine whether to display the full category path
      $category_path = true;
      //end category exclusions

      /**********************************************/

You may prevent a field from being displayed by editing it's true/false status in the $display_fields array. The other settings modify the characters used to separate multiple fields in the exclusions boxes.

### Support

You can find support for this contribution at http://forums.oscommerce.com/index.php?showtopic=213019 (OSCommerce User Forums). Please read through the common problems in the install.html file or previous postings to see if your problem or question has already been answered. If you are posting about problems with exclusions or calculations, please set the Debug Mode to true in Configuring the Order Total Module to capture debugging information and include that output in your post.

Bug fixes and new releases are added to the contribution page at http://www.oscommerce.com/community/contributions,4269.