Examples

The following examples show coupon restrictions which may be imposed:

• Creating a coupon that may only be used if have product 1 and product 5 in your cart
• Creating a coupon that may only be used if you have 4 items from manufacturer ABC in your cart
• Creating a coupon that may only be used by one customer
• Creating a coupon that may only be used by one customer group
• Creating a coupon that may only be used if you have a mix and match of 3 of products 10,11,12,13,14,15 in your cart
• Creating a coupon that may only be used if you have a mix and match 3 of products 1 and 2 and a product 5 in your cart
• Creating a coupon that may only be used by customers in pricing group 1 or 2
• Creating a coupon that may only be used if five items from category 3 are in the cart
• Creating a coupon that may only be used by non-wholesale customers (using Dual Pricing mod)
• Creating a coupon that may only be used if for carts with no sale or special items
• Creating a coupon that may only be used if item for carts containing a specific product with specific attribute settings

Overview:

My Big Chooser Extension allows you to discount products in various ways under various conditions provided certain specific items are in the shopping cart. Coupon Restrictions - Big Chooser Style takes a similar approach, but it doesn't do the discounting - it simply verifies that preconditions are met before it allows the coupon to be used. In this way, you can constrain the use of coupons beyond the limitations set by Zen Cart. (Zen Cart allows you to say a coupon only applies to certain products or categories; it does not allow you to set up complex preconditions.)

Coupon Restrictions - Big Chooser Style is configured by creating "conditions" and then parameterizing these conditions, specifying how the decision is made as to whether the condition is met, and the discounts available once the condition is met.

Coupon Restrictions - Big Chooser Style requires you to add these conditions and parameters to the module itself - they are not configured through the admin panel. This sounds complicated, but it's not that bad, and many examples of common discounting practices are provided. Please note that Coupon Restrictions - Big Chooser Style only verifies specific conditions are met prior to a coupon being used; it does not automatically add items to the cart or perform the discount.

There are two usage models for Coupon Restrictions:

• Using Coupon Restrictions with Big Chooser
• Using Coupon Restrictions without Big Chooser

Shopowners use the coupon functionality in Big Chooser because they don't want to offer the discount to all of their customers; they want it to be exclusive, based on an advertisement or an email offer or some other targeting method. Big Chooser discounts can be made conditional upon the entry of a coupon, but without Coupon Restrictions, there's no way to ensure that the required items are in the cart for the discount to be obtained. This can lead to dissatisfaction and complaints. Thus, using Big Chooser and Coupon Restrictions allows you to target a discount, and ensure the customer is actually eligible to receive it so there won't be any surprises at checkout.

Note further that the discounts which can be created with Big Chooser are significantly more flexible than the discounts permitted by coupons alone, which are limited to a percent or dollar amount off.

If you wish to use a coupon with no value in conjunction with a Big Chooser Discount, you can do so in Zen Cart 1.3.8-1.5.1 by applying my Zero Dollar Coupon changes. These are changes to includes/modules/order_total/ot_coupon.php, which must be made in order for coupons with a value of under $0.01 to work.

Using Coupon Restrictions without Big Chooser makes sense for people who want more complex restrictions than are allowed by the coupon facility natively. The coupon facility can restrict coupons to orders over a specific dollar amount, but it cannot impose a requirement that specific items be in the cart.

The calling conventions for building a condition are as follows:


So suppose the discount was as, "Coupon ABCOMBO reduces the cart total by $10 if items A (item 7) and B (item 12) are in the cart." This would be

   $this->add_condition("ABCOMBO", "Items A and B must be in the cart"); 
     $this->set_constraint(PROD, 7, 1, PROD, 12, 1); 

The statements after add_condition are the parameters. Parameter statements apply to the condition statement they immediately follow. I have provided a visual cue for this by indenting the parameter statements on this page by three spaces.

The following types of parameter statements are currently supported:

• set_constraint - specifies the items that must be in the cart to meet the condition
• set_constraint_attrfilter - specifies the attribute setting the constraint must have.
• set_choice_constraint - specifies a set of items, some of which must be in the cart to meet the condition
• set_negative_constraint - specifies the items which are excluded from the promotion; they will not be counted towards the condition
• set_group - only permit members of the listed groups to use this coupon
• set_no_group - do not allow members of the listed groups to use this coupon
• set_wholesale_level - only allow members of the listed wholesale groups (using the Dual Pricing Mod) to use this coupon.
• set_constraint_regprice - specifies that items counted towards the constraints must not be on sale or special

In addition,

• Zen Cart coupons which only apply to a single customer may be created using the technique shown in the example below.
• Zen Cart coupons which only apply to a single group may be created using the technique shown in the example below.

Examples

The discount, "You must have product 1 and product 5 in your cart to use coupon TEST1" would be specified as

   $this->add_condition("TEST1", "You must have product 1 and product 5 in your cart"); 
      $this->set_constraint(PROD, 1, 1);
      $this->set_constraint(PROD, 5, 1);

or alternately,

   $this->add_condition("TEST1", "You must have product 1 and product 5 in your cart"); 
      $this->set_constraint(PROD, 1, 1, PROD, 5, 1);

Detailed Description:

Conditions and parameters are specified in the setup() method at the bottom of the file includes/modules/coupon_restrict_chooser.php There is no admin interface; you must modify the file directly.

Note that CAT has different semantics in Coupon Restrictions - Big Chooser Style when compared to Better Together. In Better Together, CAT only includes items directly below the specified category (i.e. CAT means "parent category" based on the master_categories_id field in the products table). In Coupon Restrictions - Big Chooser Style, CAT includes all items below the specified category, whether they are directly below or in subcategories.

Men's Clothing (category 3)
     |
     ---->  Shirts (category 5)
     |      |
     |      -------> shirt A 
     |               shirt B
     |               shirt C 
     ---->  Pants (category 6)
     |      |
     |      -------> pants A 
     |               pants B
     |               pants C 
     ---->  Shoes (category 7) 
            |
            --->  Dress Shoes (category 12) 
            |     |
            |     -------> dress shoes A 
            |              dress shoes B
            |              dress shoes C 
            --->  Casual Shoes (category 18) 
                  |
                  -------> casual shoes A 
                           casual shoes B
                           casual shoes C 

Specifying "Men's Clothing" as a category in Coupon Restrictions - Big Chooser Style will include all items in Shirts, Pants and Shoes.

Specifying "Shoes" (CAT 7) as a category will include both dress shoes and casual shoes. This cannot be done in Better Together.

Note that "parent category id" is determined using the master_categories_id field from the products table. So if casual shoes A is also linked into a category called "Hot Products," the parent category is still category 18 (Casual Shoes). For more details on category handling in Coupon Restrictions - Big Chooser Style, please see the Category Issues page.

Installation Instructions:

1. Back up everything! Try this in a test environment prior to installing it on a live shop.
2. Copy the contents of the common_files folder to the root directory of your shop.
   Then copy the contents of the appropriate cart-specific version to the root directory of your shop. Choose the one that's closest to but not above yours. 1.5.0 and 1.5.1 should use the 1.5.0 folder, 1.5.2 and 1.5.3 should use the 1.5.2 folder.
3. If you have made the Zero Dollar Coupon changes before to use no value coupons with Big Chooser, you will need to make it again; they are not included in the copy of ot_coupon.php that ships with this mod.

Files

common_files/includes/functions/extra_functions/coupon_restrict_chooser.php
common_files/includes/modules/coupon_restrict_chooser.php
common_files/includes/languages/english/extra_definitions/coupon_restrict_chooser.php
<zen cart version>/includes/modules/order_total/ot_coupon.php

Formal Syntax of Conditions and Parameters

Conditions and Parameters, which are specified in the setup() function of includes/modules/coupon_restrict_chooser.php, are the mechanism for restricting coupons.

Conditions

Discounts always begin by specifying a coupon code, then a message to be used if that condition is not fulfilled when that coupon is entered. All subsequent parameters (until the next condition) apply to this condition.


where:

Coupon Code	is the coupon code, which the user will enter on the payment page of checkout.
description	Is the error message to be issued if the coupon does not meet the specified rules.

Note: The third parameter (true/false) of the add_condition statement in Big Chooser is not used in Coupon Restrictions.

Parameters - set_constraint

The set_constraint() command specifies the items which must be present in the cart for the condition to be passed.


where:

required_purchase_quantity

is the string PROD, CAT, PRICE, MINPRICE, or MANUF, followed by an identifier (product or category id, product price or manufacturer id), followed by a quantity <PROD | CAT | PRICE | MINPRICE | MANUF> <product, category or manufacturer identifier or price> <quantity>

Parameters - set_choice_constraint

The set_choice_constraint() command specifies the items which must be present in the cart for the condition to be passed.


where:

quantity	is the number of items from this choice the customer must buy; it must be numeric
required_purchase	is the string PROD, CAT, PRICE, MINPRICE, or MANUF, followed by an identifier (product or category id, product price or manufacturer id). <PROD | CAT | PRICE | MINPRICE | MANUF> <product or category identifier or price>

Note quantities are not specified per choice; the quantity is cumulative for all choices in the constraint.

Parameters - set_negative_constraint

The set_negative_constraint() command specifies the items which are excluded from the promotion; they will neither be counted towards the condition nor considered for discounting.


where:

ignored_purchase

is the string PROD, CAT, PRICE, MINPRICE or MANUF, followed by an identifier (product or category id, product price or manufacturer id). <PROD | CAT | PRICE | MINPRICE | MANUF> <product or category identifier or price>

Parameters - set_group

The set_group() command specifies that the discount is only available to members of the listed group(s).


where:

group

is the group eligible to receive the discount

Parameters - set_constraint_regprice

Require items counted towards the constraint not be on sale or special.

Parameters - set_cart_regprice

Require that all items in the cart be regular price (i.e. not be on sale or special).

Parameters - set_wholesale_level

The set_wholesale_level() command specifies that the discount is only available to members of the listed wholesale level(s), as defined by the Dual Pricing mod. (Please note that I do not support the Dual Pricing mod; this is just a way to access the data which it uses. Support for dual pricing is on the Zen Cart forum.)


where:

wholesale

is the wholesale level which is not eligible to receive the discount

Parameters - set_no_group

The set_no_group() command specifies that the discount is not available to members of the listed group(s).


where:

group

is the group which is not eligible to receive the discount

Parameters - set_constraint_attrfilter

The set_constraint_attrfilter() command specifies that the constraint items must also have the listed attributes set to the specified values.


where:

attribute id	is the id of the attribute you want set
attribute value	is the value of the attribute you want set

To get these numbers, look in Admin > Catalog > Option Name Manager and Admin > Catalog > Option Value Manager to get the ID and Value for the attributes you want.

The following attribute types may be used: dropdown, radio button, checkbox.

If multiple attribute id/value pairs are specified, only one of them needs to be set for an item to be considered to meet the constraint. For example, if you specify id 4, value 9 and id 12, value 7, then any item with either attribute id 4, value 9 OR id 12, value 7 will pass this check.

---

Major Versions

• Version 1.3 - 09/18/16 - Updates for Zen Cart 1.5.5a
• Version 1.2 - 01/02/15 - Updates for Zen Cart 1.5.4
• Version 1.1a - 08/06/14 - Additional checks for mixed case coupon/rule entry
• Version 1.1 - 07/13/14 - Updates for Zen Cart 1.5.2, 1.5.3
• Version 1.0 - 02/01/13 - First release

Restrictions and Interoperability

This mod is based on the standard Zen Cart checkout flow. It is not compatible with other checkout mods such as COWOA, One Page Checkout, Ajax Easy Checkout, etc.

NOTE: Coupon Restrictions doesn't change the discount; it just determines whether the coupon may be used or not. A common request is "please change coupons to only apply to items not on sale or special" - this requirement is not covered by this module. If you want that change, please see my Zen Cart Coupons No Sale or Special mod.

• If you are using Zen Cart 1.5.x and Edit Orders 4.x along with Coupon Restrictions Chooser, you must make the following change:
  Create a file called admin/includes/functions/extra_functions/big_chooser_lookups.php
  It should contain this code:

  <?php
  if (! function_exists('zen_get_products_manufacturers_id')) { 
    function zen_get_products_manufacturers_id($product_id) {
      global $db;
  
      $product_query = "select p.manufacturers_id
                        from " . TABLE_PRODUCTS . " p
                        where p.products_id = '" . (int)$product_id . "'";
  
      $product =$db->Execute($product_query);
  
      return $product->fields['manufacturers_id'];
    }
  }
  

Bugs

• Prior to version 1.1a, coupon codes entered in mixed case were not handled correctly.

FAQ

Q: Why is there an Coupon Restrictions - Big Chooser Style in the first place?
A: Zen Cart has some ability to restrict coupon use but not enough for some shopowners.

Q: I just want to stop coupons from applying to items on sale or special. What do I do?
A: If you want that change, please see my Zen Cart Coupons No Sale or Special mod.

Q: Why do you have to add PHP code to setup()? Why didn't you put this in the Admin panel?
A: Although it's a bit tedious to have to manually code the associations, it maximizes the module's flexibility. If you need help with the setup logic, I will be happy to do it for you for a small fee, but first look at the many examples in this page.

Q: How do I find out the manufacturer id so I can use MANUF?
A: See Manufacturers in Zen Cart for instructions.

Q: What is the difference between MINPRICE and PRICE?
A: PRICE means the price must be exactly equal to the specified value. MINPRICE means the price must be greater than or equal to the specified value. So using MINPRICE in a set_constraint means that only items of this price or greater count in the condition calculation. Using MINPRICE in a set_discount() or set_choice_discount() means that items at the specified price or greater will match the rule.

Q: I operate a multilingual shop. How can I avoid putting my descriptions in the module?
A: If you run a multilingual shop, then instead of putting the string in the add_condition() command directly, create the file includes/languages/english/extra_definitions/coupon_restrictions_chooser.php and put your definitions there as PHP defined strings. Here's an example:

<?php
  define('CONDITIONAL_MOVIE_DISCOUNT', "You must have movies A, B and C in your cart");
?>

Then, in includes/modules/coupon_restrict_chooser.php, do

$this->add_condition("COUPONABC", CONDITIONAL_MOVIE_DISCOUNT);
   $this->set_constraint(PROD, 7, 1, PROD, 12, 1, PROD, 17, 1); 

(assuming 7, 12 and 17 are the product ids for movies A, B and C).

Q: When I use PROD, it works, but I can't seem to get CAT to work. Why?
A: There are several possible root causes. Please see the Category Issues page for solutions.

Q: Why is there a set_extra_discount and set_extra_choice_discount?
A: You only need to worry about these commands if you have a discount which uses include_condition_items, and you only have to worry about this if you have a "quantity discount" style offer where the products which helped the customer meet them condition are themselves discounted. If your discount is two for one, buy 2 get 1 free, etc. you don't need to worry about these commands.

Q: All these rules and parameters and combinations make my head hurt. Will you configure this for me?
A: Naturally. Contact me with your requirements for a quote.

---