Overview:

Chooser AutoCoupon allows you to automatically add a coupon to a customer's account at purchase time based on the contents of their cart.

Chooser AutoCoupon 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.

Like Big Chooser, Chooser AutoCoupon 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 practices are provided.

The Customer's Experience

1. When the customer adds the specified set of items to their cart, the shopping cart page will indicate that they are eligible for that coupon.
2. When they check out successfully, the checkout success page will indicate that their coupon(s) have been created. The coupon codes for automatically created coupons contain the customer id of the customer they were created for and can only be used by that customer.
3. The customer's email (HTML or plain text) also includes a statement that coupons were created if applicable, with a link to the My Coupons page.
4. By clicking the prompt on the checkout success page or the My Coupons link in the Information sidebox, the customer can see the coupons that have been created for them that are currently valid for use. Coupons which have expired or have been used the maximum number of times are automatically removed from this list.

Screenshot 1: Shopping Cart Page displaying AutoCoupons

If you prefer, the expiry dates may be displayed as offsets from the current date.

Screenshot 1a: Shopping Cart Page displaying AutoCoupons

Screenshot 2: Checkout Success Page displaying AutoCoupons

Screenshot 3: My Coupons Page displaying AutoCoupons

Coupons may be displayed in one list or in two (granted, not granted).

Screenshot 4: Home Page displaying AutoCoupons

Screenshot 4a: Home Page displaying AutoCoupons (split)

The Storeowner's Experience

1. The storeowner creates a coupon with the desired specification (in terms of description, restrictions, uses per customer).
2. The storeowner defines automatic coupon creation triggers according to items purchased in various ways by modifying the setup() function in includes/modules/chooser_autocoupon.php
3. Coupons are granted to specific customers only based on the creation triggers defined in the previous step. Coupons created for one customer cannot be used by anyone else.

Configuration

Automatically created coupons are created based on "template coupons," which are set up in the admin panel (under Admin > Gift Certificate/Coupons > Coupon Admin). This is where the coupon's description, amount (or free shipping setting), minimum order, uses per customer and zone restrictions are set. For ease of identification, I suggest that template coupons be given a coupon code which begins with "TEMPLATE_" (although this is not required). To prevent someone from using this coupon directly, backdate the end date so the coupon is not valid.

The command used to create a coupon based on products purchased is add_condition.

where:

• text description: The marketing text for coupon
• template coupon code: The coupon code for a coupon you have already created from which this coupon will be cloned
• new coupon name: The name of the new coupon to be created
• lifetime count: An integer number or days, weeks or months
• lifetime units: 'D', 'W', 'M' for days, weeks or months from the date of purchase
• max times to create: 0 = no limit; 1 or more: only create this auto coupon this many times

Once these parameters are laid out, a series of "conditions" should be added to restrict the creation of the coupon to scenarios where specific purchases are made. These conditions correspond to the conditions used by Big Chooser.

So suppose you created a coupon whose coupon code was TEMPLATE_SAVETEN, which was good for 10% off.

If you would like to offer this coupon to a customer after items 7 and 9 are purchased, you would modify the file includes/modules/chooser_autocoupon.php and change the setup() function in that file to say

   $this->add_condition("Buy items 7 and 9, and get a coupon worth 10% off your next purchase",
                             "TEMPLATE_SAVETEN", "SAVETEN79", 7, 'D'); 
   $this->set_constraint(PROD, 7, 1, PROD, 9, 1); 

Adding Parameters

Once the add_condition() command has been used you may restrict the creation of the coupon to specific scenarios using parameters. These parameters specify the items which must be present in the cart for the coupon to be created. These parameters correspond to the parameters used by Big Chooser.

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

For add_condition, 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_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 total
• set_support - provide additional information on the discount
• set_deal_id - giving the discount an identifying number to allow other discounts to be filtered out if this number has been run
• set_no_double_dip - specifying which discounts which, if executed, will cause this discount to be skipped
• set_group - only apply this discount to members of the listed groups

Examples

Because the template coupons can be for anything, I will simply write <coupon description> to describe them. You would write what they actually do (10% off all products, $5 off a purchase from category 12, etc.).

The offer, "Buy product 1, get a TEMPLATE_COUPON_1 good for one year" would be specified as

   $this->add_condition("Buy name-of-product-1, get TEMPLATE_COUPON_1 description", 
                        "TEMPLATE_COUPON_1", "COUPON1", 12, "M"); 
      $this->set_constraint(PROD, 1, 1);

The offer, "Buy 3 items from category 5, get a TEMPLATE_COUPON_3 good for 6 weeks" would be specified as

   $this->add_condition("Buy 3 items from category 5, get TEMPLATE_COUPON_3 description", 
                        "TEMPLATE_COUPON_3", "COUPON3", 6, "W"); 
      $this->set_constraint(CAT, 5, 3); 

The offer, "Buy 3 items from category 5 (except product 12), get a TEMPLATE_COUPON_3 good for 6 weeks" would be specified as

   $this->add_condition("Buy 3 items from category 5, get TEMPLATE_COUPON_3 description", 
                        "TEMPLATE_COUPON_3", "COUPON3", 6, "W"); 
      $this->set_constraint(CAT, 5, 3); 
      $this->set_negative_constraint(PROD, 12); 
      $this->set_support("Product 12 not included in this promotion");

The offer, "Mix and match 3 of product 1 and product 2, get a TEMPLATE_COUPON_4 good for 90 days" would be specified as

   $this->add_condition("Mix and match 3 of products 1 and 2, get TEMPLATE_COUPON_4, 
                        "TEMPLATE_COUPON_4", "COUPON4", 90, "D"); 
      $this->set_choice_constraint(3, PROD, 1, PROD, 2);

The offer, "Group 3 Members, buy four items from category 7, get a TEMPLATE_COUPON_GROUP_3 good for 30 days" would be specified as

   $this->add_condition("Buy four items from category 7, get TEMPLATE_COUPON_GROUP_3", 
                        "TEMPLATE_COUPON_GROUP_3", "COUPONG3", 30, "D"); 
      $this->set_constraint(CAT, 7, 4); 
      $this->set_group(3);

The offer, "Buy any of product 8, 9 or 10, get TEMPLATE_COUPON_8_9_10 good for 6 months" would be specified as

   $this->add_condition("Buy any of product 8, 9 or 10, get TEMPLATE_COUPON_8_9_10", 
                        "TEMPLATE_COUPON_8_9_10", "COUPON27", 6, "M"); 
      $this->set_choice_constraint(1, PROD, 8, PROD, 9, PROD, 10); 

Sometimes you may wish to tier your discounts

   $this->add_condition("Buy 10 category 1, get TEMPLATE_HIGH_COUPON", 
                        "TEMPLATE_HIGH_COUPON", "COUPON_HIGH", 30, "D"); 
      $this->set_constraint(CAT, 1, 10); 
   $this->add_condition("Buy 2 category 1, get TEMPLATE_LOW COUPON",
                        "TEMPLATE_LOW_COUPON", "COUPON_LOW", 30, "D"); 
      $this->set_constraint(CAT, 1, 2); 

AutoCoupon does not know that these are related, so this would allow someone buying 10 category 1 items to get both coupons. To indicate that discounts are exclusive, use set_deal_id() and set_no_double_dip().

   $this->add_condition("Buy 10 category 1, get TEMPLATE_HIGH_COUPON", 
                        "TEMPLATE_HIGH_COUPON", "COUPON_HIGH", 30, "D"); 
      $this->set_constraint(CAT, 1, 10); 
      $this->set_deal_id(1);
      $this->set_no_double_dip(2);
   $this->add_condition("Buy 2 category 1, get TEMPLATE_LOW COUPON",
                        "TEMPLATE_LOW_COUPON", "COUPON_LOW", 30, "D"); 
      $this->set_constraint(CAT, 1, 2); 
      $this->set_deal_id(2);
      $this->set_no_double_dip(1);

Detailed Description:

There is no admin interface to Chooser Autocoupon; you must modify the file includes/modules/chooser_autocoupon.php Any number of these coupons may be offered.

To make these offers visible on your product info page, customize the file

includes/templates/template_default/templates/tpl_product_info_display.php

as described in marketing below in the installation instructions. This step will display the message you provided in the add_condition() command:


The message is displayed to encourage the customer to meet the condition. It is displayed on any item which will contribute to meeting the condition.

This step is optional; if you prefer, you can add your own marketing text.

Note that CAT in Spender AutoCoupon behaves like CAT in Big Spender, not like CAT in Better Together. For an explanation of this, please see this page.

Installation Instructions:

Note: initial software installation is done by me when you purchase the module. You will get a zip file of the required merges.

1. The My Coupons page is linked from the Information Sidebox. Turn this sidebox on from Admin > Tools > Layout Boxes Controller, or move the link to another sidebox.
2. Decide on the promotions you wish to use, and add them to the setup() method of includes/modules/chooser_autocoupon.php
   
   Be sure to create the matching template coupons in Admin > Gift Certificate/Coupons > Coupon Admin.
3. If you wish, follow the guidelines in marketing to advertise your offers.

Marketing

What good is having automatically created coupons if you don't advertise them?

Provided templates allow automatically created coupon offers and information to be displayed on the following pages:

• shopping cart page - the current count of autocoupons (plus a link to the My Coupons page).
• checkout success page - the number of autocoupons created by this transaction (plus a link to the My Coupons page).
• My Coupons page - accessible from Information sidebox.

To also show the available coupon promotions on the product info page, you can include this code in includes/templates/YOUR_TEMPLATE/templates/tpl_product_info_display.php

<!-- bof autocoupon -->
<?php 
 // Show the autocoupon offers currently available
 require_once(DIR_WS_MODULES. 'autocoupon_preview.php');
?>
<!-- eof autocoupon -->

This same technique is used for the front page of the shop (tpl_index_default.php).

To show the "My Coupons" link on the My Account page, include the following code in includes/templates/YOUR_TEMPLATE/templates/tpl_account_default.php after the link for MY_ACCOUNT_PASSWORD:

<li><?php echo ' <a href="' . zen_href_link(FILENAME_MY_COUPONS, '', 'SSL') . '">' . 
BOX_INFORMATION_MY_COUPONS. '</a>'; ?></li>

The following list of display customizations can be done by editing the file includes/languages/english/extra_definitions/autocoupon.php:

• You may display the preview list of coupons as a single list (integrated) or as two lists (split). Set the constant AUTOCOUPON_SHOW_LIST_INTEGRATED to 0 for split or 1 for integrated.
• You may make the coupon expiry appear as a date (e.g. "Mon Nov 3 23:59:59 EST 2008") or as an offset from the current date (e.g. "30 days"). Set the constant AUTOCOUPON_EXPIRE_AS_DATE to 1 for a date, 0 for an offset.

Formal Syntax of Conditions and Parameters

Conditions and Parameters, which are specified in the setup() function of ot_big_chooser.php, are the mechanism for configuring a store's discounts.

Conditions

Offers always begin by specifying a condition. All subsequent parameters (until the next condition) apply to this condition.


where:

description	Is a textual description of the coupon.
template coupon code	The coupon code for a coupon you have already created from which this coupon will be cloned
new coupon name	The name of the new coupon to be created. This is used internally by Chooser AutoCoupon and can be any unique string
lifetime count	An integer number or days, weeks or months
lifetime units	'D', 'W', 'M' for days, weeks or months from the date of purchase

Note that the add_condition command for Chooser AutoCoupon is not identical to the one used in Big Chooser; additional fields are added and the repeatable flag is removed.

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, or product price), followed by a quantity <PROD | CAT | PRICE | MINPRICE | MANUF> <product or category 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, or product price) <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, or product price) <PROD | CAT | PRICE | MINPRICE | MANUF> <product or category identifier or price>

Parameters - set_support

The set_support() command provides additional supporting text to describe your promotion. It is completely optional.


where:

text	is a text string, which can be plain text or a link

These strings are displayed on your promotional page, and optionally, on your product info page if you customize the file includes/templates/custom/templates/tpl_big_chooser_marketing.php

Parameters - set_deal_id

The set_deal_id() command allows you to give a condition and its associated discount an id, to allow later discounts to be filtered out if this discount has been run using set_no_double_dip. This parameter is optional and is only needed for discounts which preclude other discounts.


where:

nnnn	is some number which identifies this condition or group of conditions.

Parameters - set_no_double_dip

The set_no_double_dip() command allows you to give a specify that if a certain discount has already been run, the current discount should be skipped. This parameter is optional and is only needed for discounts which preclude other discounts.


where:

nnnn	is the id which was used in a set_deal_id() command for one or more previous conditions.

Multiple set_no_double_dip commands may be used as required.

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

Major Versions

• Version 1.0.1 - 05/12/10 - Ordered set_choice_constraint by price, not specified order.
• Version 1.0a - 02/24/09 - Fixed issue with no_double_dip.
• Version 0.2 - 10/04/08 - First release.
• Version 0.1 - 09/27/08 - Beta

FAQ

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: I have created my offers in the setup() function but they're not appearing on my home page - why?
A: There are two common causes to this problem:

• In order for them to appear on the home page, the coupon specified as the template coupon code must exist. If it doesn't, go into Admin > Gift Certificate/Coupons > Coupon Admin and create it; then you will see the AutoCoupon offers.
• The template coupon code specified in add_condition must be the coupon code (not the coupon name) from the coupon you created. The coupon code is halfway down the page on Admin> Gift Certificate/Coupons > Coupon Admin.

Q: How can I present my AutoCoupon discounts on the checkout payment page?
A: Create your custom template if you haven't already done so. Then customize the file includes/templates/template_default/templates/tpl_checkout_payment_default.php

Add to this file the following block of code:

<?php 
 // Show the autocoupon offers currently available
 require_once(DIR_WS_MODULES. 'autocoupon_preview.php');
?>

Q: How can I present my AutoCoupon discounts on the product page?
A: Create your custom template if you haven't already done so. Then customize the file includes/templates/template_default/templates/tpl_product_info_display.php Then follow the directions from the previous answer.

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_negative_constraint means that only items below this price are counted.

Q: I operate a multilingual shop. How can I avoid putting my descriptions in chooser_autocoupon.php?
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/chooser_autocoupon_defs.php and put your definitions there as PHP defined strings. Here's an example:

<?php
  define('MOVIE_COUPON_TEXT', "Buy movies 12 and 17, get a 10% off coupon for your next purchase within 30 days");
?>

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

$this->add_condition(MOVIE_COUPON_TEXT, "TEMPLATE_MOVIE_COUPON", "MOVIES", 30, 'D'); 

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

Q: I don't want the coupon to become valid until the order moves out of Pending status. How can I accomplish this?
A: At the current time, this feature is not available; if there is sufficient demand, it will be added as an extension.

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

Q: How can I create an autocoupon which is only good for a particular manufacturer?
A: You need to use Big Chooser. See Coupon Extensions for Zen Cart for some techniques.

Q: How can I create an autocoupon which can be used as a condition for a future Big Spender or Big Chooser discount?
A: See Coupon Extensions for Zen Cart for some techniques.

Q: How can I turn off Chooser AutoCoupon?
A: Modify the file includes/modules/chooser_autocoupon.php Go to the setup() function and delete or comment out all current offers.

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.

---