Overview:

Spender AutoCoupon allows you to automatically add a coupon to a customer's account at purchase time based on the total value of items in their cart.

Spender AutoCoupon is configured by creating "spending thresholds" at which coupons will be received, and then (optionally) parameterizing these thresholds. Parameters specify how the threshold is to be determined, if it is anything other than the total value of all cart items.

Like Big Spender, Spender AutoCoupon requires you to add these thresholds 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 reaches one of the dollar thresholds you have defined, 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 dollars spent in various ways by modifying the setup() function in includes/modules/spender_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 dollars spent is add_threshold.

where

• dollars spent: A threshold number of dollars (currency units) required to activate the creation of this coupon
• 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. This can be any unique string, and will become the new coupon's name.
• 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 the add_threshold command is used, a series of "parameters" may be added to restrict the creation of the coupon so that the dollars spent threshold is computed by counting only certain products. These parameters correspond to the parameters used by Big Spender in determining discounts.

So suppose you created a coupon whose coupon code was TEMPLATE_SAVETEN, which was good for 10% off. You create it and test it to make sure it works. Then you set the start and end date back before today so that it cannot be used directly.

If you would like to offer this coupon to a customer after they spend $25. You would modify the file includes/modules/spender_autocoupon.php and change the setup() function in that file to say

   $this->add_threshold(25, "Spend $25, get a coupon worth 10% off your next purchase",
                             "TEMPLATE_SAVETEN", "SAVETEN", 7, 'D'); 

Since there are no additional rules, no parameter statements are required.
If you only want to offer the coupon when $25 is spent in category 3, you would use

   $this->add_threshold(25, "Spend $25 in category 3, get a coupon worth 10% off your next purchase",
                             "TEMPLATE_SAVETEN", "SAVETEN", 7, 'D'); 
   $this->set_constraint(CAT, 3);

If you want to offer the coupon for $25 spending in all categories, but only do it once, and make the coupon valid for 6 months, you would use

   $this->add_threshold(25, "Spend $25, get a coupon worth 10% off your next purchase",
                             "TEMPLATE_SAVETEN", "SAVETEN", 6, 'M', 1); 

Adding Parameters

Once the add_threshold command has been used, you may restrict the creation of the coupon to specific scenarios using parameters. For add_threshold, these conditions constrain how the dollars spent threshold is computed by counting only certain products. These parameters correspond to the parameters used by Big Spender.

Parameter statements apply to the add_threshold 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_threshold, the following types of parameter statements are currently supported:

• set_constraint - determine whether the threshold has been crossed by totalling the value of only the specified products or categories
• set_negative_constraint - determine whether the threshold has been crossed by totalling the value of all products except those specified
• set_support - provide additional information on the offer
• set_deal_id - giving the offer an identifying number to allow other offers to be filtered out if this number has been run
• set_no_double_dip - specifying which offers which, if executed, will cause this offer to be skipped
• set_group - only apply this offer to members of the listed groups

Examples

The offer, "Spend $100, get a TEMPLATE_COUPON_2 good for 30 days" would be specified as

   $this->add_threshold(100, "Spend $100, get TEMPLATE_COUPON_2 description", 
                        "TEMPLATE_COUPON_2", "COUPON_2", 30, "D"); 

The offer, "Spend $100 on items from category 3, get a TEMPLATE_COUPON_2 good for 30 days" would be specified as

   $this->add_threshold(100, "Spend $100, get TEMPLATE_COUPON_2 description", 
                        "TEMPLATE_COUPON_2", "COUPON_3", 30, "D"); 
      $this->set_constraint(CAT, 3);

Note that set_constraint for add_coupon_spender has only two parameters; a count of items is not required.

Sometimes you may wish to tier your offers

   $this->add_threshold(100, "Spend $100 in category 1, get TEMPLATE_HIGH_COUPON", 
                        "TEMPLATE_HIGH_COUPON", "HIGH", 30, "D"); 
      $this->set_constraint(CAT, 1); 
   $this->add_threshold(20, "Spend $20 in category 1, get TEMPLATE_LOW COUPON",
                        "TEMPLATE_LOW_COUPON", "LOW", 30, "D"); 
      $this->set_constraint(CAT, 1); 

Spender 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 offers are exclusive, use set_deal_id() and set_no_double_dip().

   $this->add_threshold(100, "Spend $100 in category 1, get TEMPLATE_HIGH_COUPON", 
                        "TEMPLATE_HIGH_COUPON", "HIGH", 30, "D"); 
      $this->set_constraint(CAT, 1); 
      $this->set_deal_id(1);
      $this->set_no_double_dip(2);
   $this->add_threshold(20, "Spend $20 in category 1, get TEMPLATE_LOW COUPON",
                        "TEMPLATE_LOW_COUPON", "LOW", 30, "D"); 
      $this->set_constraint(CAT, 1); 
      $this->set_deal_id(2);
      $this->set_no_double_dip(1);

Note that when this is done, the highest offer should be specified first; otherwise, a lower offer will block a higher offer.

Detailed Description:

There is no admin interface to Spender Autocoupon; you must modify the file includes/modules/spender_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_threshold() command:


The message is displayed to encourage the customer to cross the threshold. It is displayed on any item which will contribute to crossing the threshold.

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/spender_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 Thresholds and Parameters

Thresholds and Parameters, which are specified in the setup() function of spender_autocoupon.php, are the mechanism for configuring a store's coupon offers.

Thresholds

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


where:

amount	is the cart total above which the coupon will be granted
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.
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 created	0 = no limit; 1 or more: only create the auto coupon this many times

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

Parameters - set_constraint

The set_constraint() command specifies the items whose prices are used to determine if the threshold has been passed. If this command is not specified, the total price of all items in the cart is used.


where:

qualifying_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_negative_constraint

The set_negative_constraint() command specifies the items whose prices are NOT used to determine if the threshold has been passed. If this command is not specified, the total price of all items in the cart is used.


where:

excluded_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: A negative constraint does not mean "the item must not be in the cart;" it simply means "the item is not counted towards the reaching the total."

Parameters - set_deal_id

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


where:

nnnn	is some number which identifies this threshold or group of thresholds.

For convenience, use the same id for all members of a related group of thresholds ("Spend $1000, get..", "Spend $500, get ...", "Spend $250, get ...") where you only want the highest value offer to be executed.

Parameters - set_no_double_dip

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


where:

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

Multiple set_no_double_dip commands may be used as required.

Parameters - set_group

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


where:

group

is the group eligible to receive the offer

Major Versions

• 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_threshold 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 offers 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 threshold 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 spender_autocoupon.php?
A: If you run a multilingual shop, then instead of putting the string in the add_threshold() command directly, create the file includes/languages/english/extra_definitions/spender_autocoupon_defs.php and put your definitions there as PHP defined strings. Here's an example:

<?php
  define('200_COUPON_TEXT', "Spend over $200, get a coupon for 20% off your next purchase within 30 days");
?>

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

$this->add_threshold(200, 200_COUPON_TEXT, "TEMPLATE_200_COUPON", "CPN200", 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 turn off Spender AutoCoupon?
A: Modify the file includes/modules/spender_autocoupon.php Go to the setup() function and delete or comment out all current offers.

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

---