Copyright © 2000, William Weiland
Manage coupon addition and redemption functions within a Miva Merchant 2.2x, 3.x or 4.x storefront with this plugin module.
Use the Merchant admin upload feature to upload the modules couponrd.mv and cim_coup.mv (couponrd.mvc and cim_coup.mvc with compiled versions). Also, with the compiled version, upload the cim_log.mvc. As each are uploaded, click the Add button to add them to the mall/domain. In the compiled version are two optional modules (coupimpt.mvc and couponrp.mvc) which are discussed under coupon import and coupon reports below.
In admin, under your store, click on the link for the System Extension Configuration screen. Assign the CIM Coupon Extension module and Update it to install it in your store.
In compiled Merchant admin, click on the link for Logging Configuration screen. Assign the CIM Activity Log (if it is not already assigned - it is used by many of our modules so you may already have it) to the store.
In admin, under your store, click on the link for the Fulfillment Configuration screen. Assign the Coupon Redemption module and Update it to install it in your store.
Click the link for Coupon Redemption to enter the configuration settings and add coupons.
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 4.81 you can redeem coupons
in conjunction with the Google checkout module for Miva Merchant 4.14-4.24. You
can have fixed (input blank), or percentage off (input %), and free shipping
(input S). Note if you use the free shipping coupon it will make whatever shipping
method the customer selects free.
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. In the compiled version of the coupon module is 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| Also, in the compiled
version of the module you can 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 (Merchant version 4.14+)
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. Note, this link will not
work because the coupon used in the example has expired. However, you
can copy and paste the link url as an example for your store.
Coupon Insertion 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.
If you are using the Miva Merchant User Interface (mmui) you will need to make some very simple edits to the core files. Be sure to do that with a text editor (NO WYSIWYG editors) such as Programmer's File Editor (PFE) so as not to damage the mv files. ALWAYS BACKUP your unmodified mv files in case you make a mistake.
1) In the mmui.mv file MMUI_Order_ShippingPaymentSelection function add
the following code just above the last table tag in the function. That
last table contains the Continue submit button.
<MvDO FILE = "{g.Module_Root$'modules/fulfill/couponrd.mv'}" NAME = "l.couponask" VALUE = "{Coupon_Prompt()}">
2) In the mmui.mv file MMUI_Order_Payment function add the following just
above the last table tag (same as you did in the previous instruction)(third
from the last table tag in 4.12+ - the one containing buttondraw for continue).
<MvDO FILE = "{g.Module_Root$'modules/fulfill/couponrd.mv'}" NAME = "l.couponpass" VALUE = "{Coupon_Pass()}">
3) If you are using compiled Merchant (4.14 and newer) you can have
instant coupons on the product page. In the mmui.mv file MMUI_ProductDisplay
function, add the following just above the the table row for the quantity
and add to basket button.
<TR><TD colspan="2">
<MvDO FILE = "{g.Module_Root$'modules/fulfill/couponrd.mvc'}" NAME = "l.instant_prompt" VALUE = "{Instant_Prompt()}">
</TD></TR>
Note: If you are using Merchant 4.14 or newer, the file name in the inserted code is couponrd.mvc. Also, after editing the mmui.mv, you will need to re-compile it to create the mmui.mvc. For this reason, it is highly recommended that you use the OpenUI to avoid the editing requirements.
This module can be used in both Merchant version 3.x and 2.2x. However, there is a serious, fatal error bug in one of the Miva Corp supplied core files in versions 2.22, 2.23, and 2.24. Hence, in order to use this module in those versions of Merchant, you will need to edit the db.mv file. Be sure you make a backup of this file in case you make an error. In the db.mv file, locate the function BasketCharge_DeleteAll_Module. The MvWHILE loop needs to be closed with </MvWHILE> instead of </MvIF>. If you don't fix this, you will get an error upon checkout. Again, this bug has been fixed in Merchant 2.25 and 3.x so you only need to make the file correction in Merchant 2.22, 2.23, and 2.24.
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.
Install the coupimpt.mvc in the domain. It is accessed under admin:stores: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 OpenUI token areas. However, you would not want to place the token in a screen that is repeatedly run. Perhaps the invoice screen header would be useful. 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.
Install the couponrp.mvc in the domain. Assign it to the store at admin:stores: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: If you are using the Miva Merchant look and feel, there are edits of the mmui.mv required. Instead of editing the mmui.mv source, using the OpenUI Look and Feel is preferred.
Q: After the customer enters the coupon code, the discount is not applied to the order.
A: Make sure that the cim_coup (CIM Coupon Extension Module) is "assigned" to the store under the store's System Extension Configuration screen.
Q: I installed the compiled version of the coupon 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, remove the admin input for Instant Coupon Prompt.
Q: I am using template screens in the compiled version of Merchant during checkout. How do I incorporate the coupon prompts since the OpenUI hook points are not on those template screens?
A: In the OpenDesigner (and other page template systems) you can use OpenUI module tokens in the format %module|couponrd|x15_20% instead of hook points at 15_20 and 14_31. So on the OSEL screen, you would use %module|couponrd|x15_20% and then on the OPAY screen, you would use %module|couponrd|x14_31%. On both screens, the token has to be within the form for those pages, probably just above the Continue button input. Also, if you want the instant coupon prompt (promotion code) on the product pages with Merchant versions 4.14-4.2x, use the token %module|couponrd|x17_18%.
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 4.81 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 4.80 or older, you will need to update the coupon module through the store you got the original from.
Still have a question?