Copyright © 2000, William Weiland
Manage coupon addition and redemption functions within a MIVA Merchant 5.x storefront with this plugin module.
You will install three modules (couponrd.mvc, couponrp.mvc, cim_log.mvc).
Install couponrd.mvc
1) In admin, click Add Modules link (fig 2)
2) Click the file upload button
3) Browse to find the couponrd.mvc file on your hard drive and upload (fig 3)
4) Click Add to add it to the domain
5) Then in admin click on the plus to the left of Stores
6) Click the plus to the left of your store name
7) Click on Order Fulfillment Configuration link (fig 9)
8) Check the box next to the Coupon Redemption
9) Click Update
10) Click on System Extension Configuration link
11) Check the box next to the Coupon Redemption
12) Click Update
13) Click on the Shipping Configuration link
14) Check the box next to the Coupon Redemption
15) Click Update
16) Click Pages link to get to the User Interface (fig 4)
17) Click Items link at the top of the User Interface page (fig 5)
18) Click the Add Item button (fig 6)
19) Enter couponrd for the code (fig 8)
20) Look up and scroll to the last page of items and Coupon Redemption should be at the end of the list of items
21) Select Coupon Redemption
22) Click the Add button to assign the module
Install couponrp.mvc
23) Again, click Add Modules link
24) Click the file upload button
25) Browse to find the couponrp.mvc file on your hard drive and upload
26) Click Add to add it to the domain
27) Click on the word Utilities
28) Check the box next to the Coupon Utility
29) Click Update
30) The CIM Activity Log (cim_log.mvc) may already be in your store as it is used by many of our modules. Check under the Modules link to see if it is already there. If it is there, skip to 39. If not, then go to 31.
Install cim_log.mvc
31) Again, click Add Modules link
32) Click the file upload button
33) Browse to find the cim_log.mvc file on your hard drive and upload
34) Click Add to add it to the domain
35) Click on the Logging Configuration Link
36) Check the box next to the CIM Activity Log
37) Click Update
38) Skip to 44
Update cim_log.mvc
39) Click Modules link
40) Scroll down to CIM Activity Log and click the link
41) Click the file upload button
42) Browse to find the cim_log.mvc file on your hard drive and upload
43) Click Update to update the module
Configure the module
44) Return to the Order Fulfillment Configuration screen and click the link for Coupon Redemption (admin) to enter the configuration settings and Coupon Redemption (coupons) to add coupons
Editing Requirements
45) After configuring the module, insert the tokens per the Editing Requirements section below
An unlimited number of coupons can be assigned to the store and each identified with a coupon code. Once you have added the module to the store, you can add coupons in the Order Fulfillment section of the admin interface. When you select the Add icon, you will have several input fields to fill in.
Coupon ID
You must enter a unique code for your coupon. This
is the code that you will give to customers so they can shop and redeem
the coupon. It can be any combination of letters and/or numbers.
Expiration Date
An optional expiration date can be included which will prevent its use
if the date has passed. Enter it in the year, month, day format, eg.
20000724 would be July 24, 2000. If you leave this field blank the
coupon will never expire. However, you can still delete it manually
through the admin interface.
Redemption Value In the compiled version of the coupon module you can assign a coupon to
remove the shipping charge. It has no specific value (using .01 for the
value is fine) as it will eliminate the shipping charge no matter how much
it is. To use this option, put the letter "S" (upper case) in the separate
field to the right of the redemption value (the same input you would have
used for the % option). Beginning with coupon module version 4.56, you can
also use the letter "P" for free shipping AND a percentage discount or the
letter "F" for free shipping AND a flat value off. The discount is
calculated the same as leaving the field blank (for the F) or entering a
% (for the P). The letters P and F cannot be used if you offer Google checkout
in your store. Beginning with coupon module version 5.013 you can redeem coupons
in conjunction with the Google checkout module for Miva Merchant 5.x. You
can have fixed (input blank), or percentage off (input %), and free shipping
(input S). Note if you use the free shipping coupon Google will make whatever shipping
method the customer selects free. If you are using the CBS Shipping Supermod, the
free shipping coupon will also make whatever shipping method the customer chooses free.
The coupon code will not be included in the CBS shipping method line item.
A flat value OR percentage off the order total is assigned to each coupon.
The default is flat value, eg $5.00 off the order total. If you put the
% sign in the next input field AFTER the value field, it will calculate
the coupon value based on the assigned percent of the order total. Note:
only include numbers or decimal in the value field. The %, if used, is
entered in the separate field to the right for that purpose. If left
blank, the calculation will be based on the raw value of the coupon. See
the note below about restricting calculations to specific products.
Minimum Order
Optionally, a coupon can be allowed only when an order total reaches a
specific amount. In all cases where a raw value is used, you must make
this value equal to or greater than the value of the coupon. If you use
the percent calculation, this value can be any value, including zero.
Reduce Tax
Based on your state's tax requirements, the coupon can be designated to
reduce the sales tax or not reduce it. For example, in some states, a
store coupon reduces the value of products purchased before the sales tax
is applied, hence you would want it to reduce tax. The exception to doing
this is if your products are likely to be non-taxable, making a coupon
reduce tax could result in a negative tax calculation. Another type
coupon might be the manufacturer coupon. In some states, manufacturer
coupons do not decrease the tax liability. You should determine your
state's tax requirements before adding coupons to your store.
Coupon Usage
- multiple times - The coupon can be used at every visit by any customer
who shops at your store. This is usually used as a promo to customers,
user lists, clubs, etc. They often have a short expiration date to limit
their use. A typical usage might be a special holiday sale, eg 10% off
everything in the store if used by a specified date. This would eliminate
the need for special price groups if the intent is that everybody who has
the coupon code can use it. In the compiled version of the module, just
below the selection for usage, there is an input for the number (#) of
times the specific multiple coupon can be used. When an order is completed,
the coupon becomes used. It is possible that the usage limit can be exceeded
if a customer puts one of them in their basket during checkout while there is
still one remaining. But before their order completes, someone else completes
an order who also had the last one in their basket. This is a limitation
you should be aware of when deciding how you will use the limit feature of
multiple times coupons.
- only one time for each customer - The coupon can only be used for one
visit per customer. When the same customer shops at your store a second
time, if he/she uses the same coupon code, it will be rejected. This is
probably the most common coupon and is usually used in print ads or as
a promo, eg. "$5.00 off on your next visit". Note: This type cannot be
used with Google Checkout since the Google module does not supply the customer info
when redeeming coupons.
- only one time for a unique coupon code - The coupon can only be used
once. Once any customer has used this code, it becomes unavailable for
any other purchase. This is often used as a customer relations tool, eg
"sorry for the inconvenience, please accept this coupon.....".
Product Code Specificity
You can restrict usage of a coupon in your store so that it can be used
only if a specific product code is ordered. You can list several product codes,
any of which in the basket would make the coupon valid if the other
requirements are met. Caution: do not put the same product code in the
list more than one time. Leaving the product code blank means that customers
do not have to order a specific product as long as they meet the other
requirements the store owner has specified. If you check the box to the
left of the product code list, and are using the percentage discount,
only those products in the code list will be used in the calculation. If
you do not check the box, the percentage will be applied against the
order total. You can use an asterisk to create a wildcard of product codes.
It only works with the first few letters of the product codes. So if you
enter 1AA*| as the input, all product codes which BEGIN with 1AA will be
eligible. The coupon module has the ability
to restrict the coupon usage down to the attribute level. For example,
you can limit the coupon to product codes beginning with
1AA and the attribute "Version" with the option of "4.5". The
format for the input would be 1AA*~Version~4.5| You can also create a coupon
that can be used for all items except those specified in a list. For
excluding, put the minus character at the beginning of the list. Example:
-ABC|XYZ|NOP| would exclude those three products from activating the coupon.
You cannot use excluded coupons down to the attribute level. Keep in mind when
excluding products that if any product in the basket is not in the exclude list, the coupon
will be valid.
Location Restriction
In the compiled version, you can limit the usage of a coupon to a specific area/zone. Begin the input
with one of these: SC- SS- SZ- BC- BS- BZ- The first letter indicates the
ship to (S) or bill to (B) address to be compared to the restriction list.
The next letter indicates the scope of the zone: country (C), state (S), or
ZIP code (Z). Then follow that with a hyphen. After that you would put in
the eligible location codes separated with the | as a delimiter. Thus, if
you put SC- at the beginning, you might continue the input with US|CA|MX to
result in SC-US|CA|MX This would indicate that a coupon can only be used
if the ship to country is either United States, Canada, or Mexico. There
is a special code if you want to limit it to the United States but exclude
Alaska and Hawaii. Use the code USX for this special condition. If you
use state limiting, the state codes used may be the same as state codes in
a different country. The ZIP code match is for 5 digit ZIP codes. Most
likely you will only use this feature for the country comparison and for
coupons for free shipping. You may not want to provide a coupon for free
shipping for customers outside of your native country. I've included the
state and ZIP in case you might want to have some local area specials.
Instant Coupons
If you check the box labeled "Instant", the coupon can only be used on the
individual product screen. Instant coupons vary from the regular checkout
coupons in that more than one instant coupon can be redeemed in a single
order. Because they are redeemed at the product screen (before checkout),
they do not have the restrictions on order subtotal or order location nor
can they be used for free shipping.
Thus, don't create a fixed amount $5 coupon for a $4 product. Always
make sure the value of instant coupons are appropriate to the product
you are assigning them to. Instant coupons must have one or more products
listed in the input for "Activate with these product codes...." in order
to calculate discount. Percentage off coupons are more appropriate
when you are allowing the instant coupon to be redeemed with more than one
product code. Likewise, they are not limited to the multiple coupon
limitation number within a single order because the multiple usage is
not recorded until the order it completed. You need to consider that
these coupons will provide additional discount for multiple quantities
of eligible products. They also cannot restrict to one per customer because
they are redeemed before the customer even logs in. If you do not want to
use the instant coupons, remove the admin input for Instant Coupon Prompt.
Instant coupons are particularly useful if you want to send out a link in
an email with the product code and coupon code in the link so the customer
can click the link and it puts the product and coupon in the basket
automatically. In this example, I have 3 attributes pre-defined. If you
have a product with attributes and you want to stuff the attributes,
you'll need to use %5B and %5D to replace the [ and ] in the link url.
If you are coping and pasting a url into the browser, brackets are
ok. But as a link, you need them converted.
Coupon Insertion Example
You can alternatively use a form, for example:
Deleting Expired Coupons
Expired coupons can be removed from the database (to cut down on disk
usage) one at a time or in mass. In admin, you can either put a check
in the remove column and select update or select purge expired coupons,
then select update.
The module is called within specific template screens with render tokens. They are in the format of
<mvt:item name="itemcode" param="xxxx" />
The templates are listed at the Pages link. You will edit the template by inserting the token and clicking the Update (fig 7). Important: After adding the render token to a template page, you must click the Items link for that page, scroll down to the item name and assign it to the page (fig 8). These two steps are repeated for every page that a module's render token is used on.
1) On page 'prod' (product display), click the tab at the top labeled Product Display Layout. Then near the bottom, if the template code is not exposed, click the link for Advanced Mode. Insert
<mvt:item name="couponrd" param="prod" />
on the page. You may insert it within an existing table cell or create a new table row with cell(s), e.g. wrap the token with <tr> <td> (token here) </td> </tr>
2) On page 'osel' (shipping/payment selection), insert
<mvt:item name="couponrd" param="osel" />
just above the continue button code and the closing </form> tag.
3) On page 'opay' (order payment), insert
<mvt:item name="couponrd" param="opay" />
just above the continue button code and the closing </form> tag.
4) If your products have attributes and you are going to use the instant (product page) coupons, you will need to add a hidden input to the 'patr' missing product attribute page template within the form with the other hidden inputs. The input to add is
<input type="hidden" name="coupon_id45" value="&mvte:global:coupon_id45;">
Coupon codes are entered at the checkout screen which also displays the shipping and payment selections. Appropriate error messages are displayed when coupons do not meet the usage criteria established by the store owner. When the shopper enters a coupon code at checkout that is not valid based on the criteria you establish, he/she will see an error message just below the coupon code input when the checkout form is re-displayed after the validation step. Customers are allowed to redeem one coupon per order.
Additionally, if customers go back to the basket and remove items which previously qualified them for a coupon, then go to checkout, they will not be able to get past the coupon validation step with a coupon not meeting the pre-established criteria.
A historical database, which can be imported and analyzed in database or spreadsheet software, is maintained on all coupons used. The couponuz.dbf can be FTPd to your PC for further analysis in MS Access, MS Excel, or other data management software. This could be useful in determining which coupons bring you the most activity.
The coupon utility for importing is accessed under admin:storename:utilities:import
Upload the flat file containing coupons through admin. Name the flat file
coupimpt.dat. It contains the coupon code, expiration date, value,
minimum order amount to qualify, reduce tax, usage once or many or one per
customer, good for which codes, good only for specific codes when
calculating, calculate as flat of percentage, maximum redemption value,
limit to number of uses, instant coupon on product page, zone. For
example:
SPRINGSALE^20020621^10.00^0.00^1^O^1AA0*|^1^%^50.00^0^0^SC-US|CA
Leave the last line of coupimpt.dat blank
The above fields are:
- Coupon code in upper case letters or numbers
- Expiration date as YYYYMMDD
- Redemption value
- Minimum order amount equal to or greater than the redemption value if the redemption value is a flat amount
- Whether to make a taxable or non-taxable deduction (1 = yes, 2 = no)
- Usage: M = multiple times, O = one per customer, S = single use
- Good for specific codes. Normally a list of product codes, each terminated with a | character. You can use an asterisk (*) as a wild card, ie all product codes beginning with 1AA0 in the above example would apply. The asterisk only applies to the beginning characters in the product codes.
- Good only for the product codes listed. If 1, then the discount will only be calculated for the eligible product codes when applying the percentage calculation. If 0, then the discount will apply to all products in the order if using the percentage calculation.
- Calculation is either empty if the coupon is a flat amount value or a % if it is to be multiplied times the cost of products. If it is to be used for free shipping, use S.
- Maximum value is used when limiting the redemption value of a coupon which is a calculated percentage. This number is not necessary if the value of the coupon was already set as a flat amount.
- Limit is the number of times a coupon can be used if multiple usage. Leave as 0 if not limited.
- Instant determines location for coupon redemtion; 1 is on product page, 0 is at checkout
- Zone is a | separate list of country codes if you want to limit the coupon usage.
You can generate a unique code and display that code to the customer at runtime.
The first step is to create a coupon template. You create it just like you create all other coupon codes except for two fields. The ID must begin with the # character. Then it is followed by a number, e.g. #3 The other field which is different is the date of expiration. Instead of a fixed date in the format YYYYMMDD, you will enter the number of days from the coupon code generation, e.g. 10 You should keep the expiration short to minimize the number of coupons in your system and promote short term redemption.
Then, using a module like our Mail Manager, you will include the token to run the coupon generator. As an example, the token %module|couponrd|3% could be inserted in a Mail Manager generated welcome email or its customer confirmation email. Every time that email with token is run, a unique coupon code with parameters matching the template would be created and displayed to the customer. Hence, the #3 template would be used and would have an expiration 10 days from the current date of the email. If you don't have our Mail Manager module for generating HTML formatted emails, you can place the token in the token areas of other email modules capable of using this style token. That said, you may want to invest in our Mail Manager module as its features are similar to other HTML formatting email modules and is much less expensive.
An advanced feature in the coupon generator is the ability to prepend a series of characters before the unique coupon code. For example, suppose we want to prepend FLW- to all of the coupon codes generated through our Follow-on Contact module. In the coupon module we could have a template with the ID of #4~FLW- Then in the contact email body we could include the token %module|couponrd|4~FLW-% The required portions of this 3rd parameter are that the parameter begins with a number. The number is followed with the tilde character (~). Then the characters we want prepended to the random, unique code. This would result in a coupon code like FLW-LPQTSMVR The beginning is a constant (FLW-) which is easily tracked in the report module so you can judge effectiveness of specific marketing campaigns. The next eight characters are randomly generated. Keep in mind that this has the ability to automatically generate hundreds or thousands of unique coupon codes so you will probably want to keep your expiration time short.
Another use of the coupon generator is to generate a unique coupon on any template page in your store. The format of a render token is a little differnt from the module token. As example, to put a render token on a template page, you would use the token <mvt:item name="couponrd" param="3" /> which would have the same result as the #3 module token above.
If you use multiple use coupons and have a limit set and want to display the number remaining of a specific coupon code to customers, you can use a token to retrieve the amount as a variable. Then display a message. You would use a render token in the format <mvt:item name="couponrd" param="~XXXXXXXX" /> where you want a to calculate the number of a specific multiple coupon remaining when it is limited. Begin the param with "~". The "XXXXXXXX" represents the coupon code. After calculating, you can access the variable cim_multi_coupon_remaining to display that number with standard Miva page template code. As example, let's say you are running a sale on your site for the first 20 customers. You could include the following code (example coupon code here is DEALS) on the storefront or whereever you thought is would be noticed. Don't forget to also assign the couponrd item under the item list for the page you put it on.
<mvt:item name="couponrd" param="~DEALS" />
<mvt:if expr="g.cim_multi_coupon_remaining GT 0">
&mvt:global:cim_multi_coupon_remaining; DEALS coupons remaining
<mvt:else />
All DEALS coupons have been used
</mvt:if>
Under admin:storename:utilities you can summarize or list each coupon used for a specific time period. You can also restrict the output to a specific coupon code or a string of characters in a coupon code. This latter is useful when you have assigned a series of coupons to an affiliate or advertising campaign. You can determine how much business was brought in with the coupons from various sources.
Q: The prompt to enter the coupon code during checkout is not showing up.
A: Make sure you insert the render token in the template for the osel page and you assigned the Coupon Redemption under the list of items. Then, check the opay, prod, and patr template pages for those two required steps.
Q: After the customer enters the coupon code, the discount is not applied to the order.
A: Make sure that the Coupon Redemption module is "assigned" to the store under the store's System Extension Configuration screen.
Q: I created an instant coupon for redemption on the product screen. After the customer enters the coupon code, the discount is not applied to the order.
A: Make sure that the CIM Activity Log module is "assigned" to the store under the store's Logging Configuration screen.
Q: I installed the module and now there is a promotion code prompt showing on the individual product screens. I only want to redeem coupons during checkout so how do I get rid of the input on the product screen?
A: If you do not want to use the instant (promotion) coupons on the product screen, erase the text in the input at admin > stores > order fulfillment configuration > coupon redemption (admin) for Instant Coupon Prompt and/or do not put the render token on the prod template page.
Q: In the Order Fulfillment Configuration:Coupon Redemption (Coupons) there is a Go To: text area. What is that for?
A: It is so you can skip to the coupon you are looking for without having to click screen after screen. If you have a coupon code of XYZ, then you would enter XYZ in the input and click update.
Q: I have installed Google Checkout module in my store and I don't know how to configure it to use coupons.
A: If you are using my coupon module version 5.013 or newer, you can add it as an "extension" to the Google Checkout module. Adding extensions is covered in the instructions that come with the Google Checkout module. The module code to use is couponrd. If you are using coupon module version 5.012 or older, you will need to update the coupon module through the store you got the original from.
Still have a question?
