That Software Guy! eCommerce Starts Here!
Coupon Restrictions - Big Chooser Style

Zen Cart Coupon Restrictions - Big Chooser Style

A module for Zen Cart™ that allows you to restrict the use of coupons based on whether certain products are in the cart. Coupon Restrictions doesn't change the discount; it just determines whether the coupon may be used or not. If the coupon can be used, the behavior is unchanged.

Example Discounts: I have provided several examples of Zen Cart Coupon Restrictions Chooser discounts.

Relevance: Zen Cart™ 1.3.9, 1.5.x
See interoperability for restrictions.

Current Version: 1.3. Occasionally, new features are documented prior to being publicly available; please check the version history to ensure the feature you want is available in your version.

Support Thread: My commercial software is not supported on the Zen Cart forum. Please email me questions instead.

Cost: $60 (Upgrade for Zen Cart 1.3.x from prior version - $10) (Note: this low price covers software only for self-installation.)



Would you like to ask me questions before buying? I'm happy to help likely purchasers make the right decision. Just email your inquiry to . Please be sure to include your cart type and version (e.g. Zen Cart 1.5.1, OpenCart 2.3.02, osCommerce 2.4, etc.) and the mod you want to buy.

Installed Cost: $120.00 (Professional installation by That Software Guy)

Installation Difficulty: Moderate (You must write some PHP to configure this mod; there is no Admin panel)

Installation Instructions: click here

Buy: Buy Coupon Restrictions - Chooser Style. Or email your pre-purchase question to .

Bugs: click here

FAQ: click here


Examples

The following examples show coupon restrictions which may be imposed:

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:

{ coupon code, error message }

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,

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);


If you need 4 items from manufacturer ABC to use coupon ABC10, it would be specified as

   $this->add_condition("ABC10", "You must have 4 items from manufacturer ABC"); 
      $this->set_constraint(MANUF, 7, 4); 
(assuming the manufacturer id of ABC was 7).

Creating a coupon which may only be used by one customer is simple. Just use a coupon code of the form "CID_x_some-string" when creating the coupon, where "x" is the customer's customerid, and "some-string" is whatever you'd like. For example, the coupon codes "CID_27_WELCOME" and "CID_27_012813" and "CID_27_MAR2013" may all only be used by customer 27. No additional coding is required.

Note: The customer's customerid is the numeric value which is the leftmost field shown in Admin->Customers->Customers.

Note: if this is the ONLY restriction you need, please also see Coupon Single User

Creating a coupon which may only be used by one group works the same way. Just use a coupon code of the form "GID_x_some-string" when creating the coupon, where "x" is the group id, and "some-string" is whatever you'd like. For example, the coupon codes "GID_2_WELCOME" and "GID_2_012813" and "GID_2_MAR2013" may all only be used by group 2. No additional coding is required.

Note: The name of the customer's pricing group is shown on Admin->Customers->Customers; go to Admin->Customers->Group Pricing; and look up that Group Name; the leftmost field on that screen is the group id.

A coupon code MM3 requiring, "Mix and match 3 of products 10,11,12,13,14,15" would be specified as

   $this->add_condition("MM3", "You must have 3 of products 10,11,12,13,14,15");
      $this->set_choice_constraint(3, PROD, 10, PROD, 11, PROD, 12, PROD, 13, PROD, 14, PROD, 15);


A coupon code MM3PLUS5 requiring, "Mix and match 3 of products 1 and 2 with a product 5" would be specified as

   $this->add_condition("MM3PLUS5", "You must have 3 of products 1 and 2 and 1 of product 5");
      $this->set_choice_constraint(3, PROD, 1, PROD, 2);
      $this->set_constraint(PROD, 5, 1);


To make the coupon "GROUP_1_2_ONLY" only available to group 1 and 2 members, use

   $this->add_condition("GROUP_1_2_ONLY", "Available to group 1 and 2 members only");
      $this->set_group(1,2);


To restrict Coupon 5CAT3 so that it may only be used if five items from Category 3 are in the cart, use

   $this->add_condition("5CAT3", "You must have 5 items from category 3");
      $this->set_constraint(CAT, 3, 5);


To restrict Coupon RETAIL1 so that it may only be used by non-wholesalers (if the Dual Pricing mod is used), use

   $this->add_condition("RETAIL1", "Sorry, this coupon is not applicable to wholesalers");
      $this->set_wholesale_level(0); 


To restrict Coupon SAVE10NOSALE so that it may only be used when regular priced items (i.e. no sale or special items) are in the cart, use

   $this->add_condition("SAVE10NOSALE", "Sorry, this coupon may not be used when items on sale or special are in the cart");
      $this->set_cart_regprice(); 


To restrict Coupon TWO_USB_MOUSE so that it may only be used when two product 26 with attribute 3 set to 9 (Model set to USB), use

 $this->add_condition("TWO_USB_MOUSE", "You must have two USB Microsoft IntelliMouse in your cart");
     $this->set_constraint(PROD, 26, 2); 
     $this->set_constraint_attrfilter(3, 9);


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.

$this->add_condition(<Coupon Code>,<description>);

where:
Coupon Codeis the coupon code, which the user will enter on the payment page of checkout.
descriptionIs 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.

$this->set_constraint(<required_purchase_quantity 1>[,<required_purchase_quantity 2>,...,<required_purchase_quantity n>]);

where:
required_purchase_quantityis 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.

$this->set_choice_constraint(<count>,<required_purchase 1>,<required_purchase 2>[,...,<required_purchase n>]);

where:
quantityis the number of items from this choice the customer must buy; it must be numeric
required_purchaseis 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.

$this->set_negative_constraint(<ignored_purchase 1>[,<ignored_purchase 2>,...,<ignored_purchase n>]);

where:
ignored_purchaseis 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).

$this->set_group(<group 1>[,<group 2>,...,<group n>]);

where:
groupis the group eligible to receive the discount


Parameters - set_constraint_regprice

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

$this->set_constraint_regprice();



Parameters - set_cart_regprice

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

$this->set_cart_regprice();



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.)

$this->set_wholesale_level(<wholesale 1>[,<wholesale 2>,...,<wholesale n>]);

where:
wholesaleis 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).

$this->set_no_group(<group 1>[,<group 2>,...,<group n>]);

where:
groupis 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.

$this->set_constraint_attrfilter(<attribute id 1>,<attribute value 1>[, ... <attribute id n>,<attribute value n>]);

where:
attribute idis the id of the attribute you want set
attribute valueis 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

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.



I charge a fee of $60 for Coupon Restrictions - Big Chooser Style. Buy Now.
The fee covers software only; installation is extra if you require help.