| QWK | QwkPromo |
Documentation for version 2.321006.
Copyright © 2004-2005, QwkSoft. Licensed to 4TheBest eCommerce Solutions.
QwkPromo gives you the ability to define a variety of sales, coupons and other promotions.
Promotions can be configured so that they are triggered by date, basket contents, affiliate associations, and / or the entry of a promotion or coupon code.
The promotion can give the customer a flat discount, a percentage discount, the cheapest product free, or free shipping. The discount or other premium can be limited to the same products that triggered the premium, or to a different set of products.
The QwkSoft Promotion Manager distribution contains 4 files: qwkpromo.mvc, qwkpromo_l.mvc, qwkpromo_s.mvc and qwkpromo.html (this documentation file). Install the *.mvc files in your domain and store as usual for Miva Merchant modules. Please refer to the documentation for your version of Miva Merchant for more information.
note: if you are using a non-compiled version of Miva Merchant you will need the non-compiled version of this module. That distribution contains *-nc.mv files in place of *.mvc files.QwkSoft Promotion Manager is a Store Utility module. It also uses Logging and System Extension modules that must be installed in the store, but have no databases or settings of their own. Store Utilities Screen
This module places 17 tabs on the Store Utilities screen. This screen can be reached from the left navigation bar by selecting Stores->your store name-> and then selecting this module.
(Some tabs may not be visible at all times)
View, add or edit Settings record.
These settings affect the overall behavior and appearance of the software.
The following tokens are available in the error messages ( though not all will have meaning in all error messages )
| full | The full promo or coupon code as entered by the customer |
| code | The promo code as it appears on the promo record |
| name | The promo name as it appears on the promo record |
| desc | The promo description |
| detail_url | The URL to a page displaying the promo details |
| detail_link | A formatted hyper link to the page containing the promo links. Blank if there is no detail URL |
| use_count | The number of times this coupon has been used. |
| use_limit | The limit to the number of times this coupon can be used. |
Determines what happens when the order qualifies for multiple promotions.
| Options | |
| Apply All |
Apply all promotions |
| Use Highest |
Apply the promotion that results in the highest discount. |
| Use Lowest |
Apply the promotion that results in the lowest discount. |
| Use First |
Use the first promotion that the order qualifies for. |
| Use Last |
Use the last promotion that the order qualifies for. |
Limits the total discount to the indicated percent of the total of all products. If giving applying a given promotion to the order would exceed this amount, the promotion is skipped.
Limits the total discount to the indicated percent of the total of all products. If giving applying a given promotion to the order would exceed this amount, the promotion is skipped.
The error message shown to the customer when they enter a promotion or coupon code for a promotion that has not yet started.
The error message shown to the customer when they enter a promotion or coupon code for a promotion that has ended.
The error message shown to the customer when they enter a promotion or coupon code that does not exist, or a promotion code containing an invalid affiliate.
The error message shown to the customer when they enter a promotion or coupon code twice.
The error message shown to the customer when they enter a coupon code which has already been used.
The defalt message generated when the customer enters a promotion or coupon code that is valid, but that they don't qualify for currently. For example; this message would be generated if the customer entered a promotion code that gave them free shipping on orders of $100 or more, but had not yet placed $100 worth of products in their basket.
This message can be overridden on a promotion by promotion basis. Also, this message will not show at all unless the Show message if not qualified box is checked for on the Promotion Settings tab.
Indicates where to look for the affiliate code in customer-entered promotion codes.
| Options | |
| n/a |
Do not look for affiliate codes. |
| before |
Look for affiliate codes as a prefix to the promotion code. |
| after |
Look for affiliate codes as a suffix to the promotion code. |
Indicates how the affiliate code is separated from the promotion code.
| Options | |
| - (dash) | |
| _ (underscore) | |
| / (slash) | |
| . (period) | |
If checked, QwkPromo will not recalculate promotion eligibility when saving order information ( the ORDR action )
If checked, QwkPromo will not recalculate promotion eligibility when calculating tax ( the CTAX action )
If checked, QwkPromo will not recalculate promotion eligibility when calculating shipping ( the SHIP action ). Note: selecting this option will make the "free shipping" premium option work incorrectly.
Lists Promotion records.
Click the [add] link on the right side of the header line to add a new record.
Click the [edit] link on the right side of a line to edit the record.
Check one or more boxes in the delete column on the left of the list and click the update button at the bottom of the list to delete the selected records.
Click <-prev or next-> in the footer to move backwards or forward a page. Enter a new value in the field label "page" to change the number of records per page.
Lists Global Affiliate records.
Check one or more boxes in the delete column on the left of the list and click the update button at the bottom of the list to delete the selected records.
Click <-prev or next-> in the footer to move backwards or forward a page. Enter a new value in the field label "page" to change the number of records per page.
View, add or edit Promotion record.
The promo code. You will give this to the customer and they will type it in to get the discount. Depending on other settings, this may need to be combined with an affiliate code to be used, or may be ignored in favor of a coupon code.
The name of the promotion. This text will appear in the customers basket and on their invoice.
A longer description of the promotion. Handy for describing the requirements of the promotion to the customer.
Specifies when the description for this promo appears on the description screen.
| Options | |
| always |
Always show the description for this promo. |
| date |
Show the description for this promo when the date is within the promo's date range. |
| qualified |
Only show the description for this promo when the customer qualifies for this promotion. |
| premium |
Show this promotion when the customer is actually receiving a premium. Please note that this could have odd results when the premium is free shipping. |
| never |
Never show this premium on the summary screen. |
The number of times this promotion has been used.
The total value of the discounts or premium received using this promotion code.
This specifies when the promotion is activated.
| Options | |
| Always |
The promotion is always active if all the criteria are met. In other words, the customer does not need to enter a promotion code to get the premium. |
| Promotion Code Entered |
The promotion is triggered when the customer enters the promotion code. There are no limits to how often a promotion code be entered. |
| Coupon Code Entered |
The promotion is triggered when the customer enters a coupon code associated with the promotion. Promotions can be configured so that each coupon code can only be used a limited number of times, or for a limited amount of discount. See below. |
The number of times that each coupon associated with this promotion can be used, typically 1. This has no effect if "When" is not "Coupon Code Entered."
The total amount of discount that each coupon associated with this promotion can be used for.
Indicates the relationship between Affiliates and promotions.
| Options | |
| Ignore Affiliate |
Affiliates have no relation to promotions. |
| Require Affiliate |
An Affiliate must be associated with the customer for the promotion to be activated. |
| Optional Affiliate |
An Affiliate can be associated with the customer. |
If affiliates are associated with promotions, this indicates how the association is established
| Options | |
| On Basket |
The association is established by looking for affiliate information on in the basket information. This is usually set because the customer followed a link with the affiliate encoded in it. |
| In Promotion Code |
The association is established by looking for the affiliate code as part of the promotion code entered by the user. Whether the affiliate precedes of follows the promotion code, and how the two are separated is determined on the main Settings screen. |
| Either |
The association is established in either way, with the promotion code being checked first. |
Determines if there is a limit to which affiliates count
| Options | |
| Any Active Affiliate |
Any active affiliate counts. |
| Affiliate on Global List |
Only those affiliates on the global list of affiliates count. |
| Affiliate on Promotion List |
Only those affiliates on the promotion specific list of affiliates count. |
Determines if a minimum purchase is required, and if so whether that minimum is based on the number of items, or their total value.
| Options | |
| None |
No minimum purchase is required |
| Amount |
The customer must purchase a minimum amount of product based on the price of the product. The amount is specified below. |
| Quantity |
The customer must purchase a minimum number of products. The quantity is specified below. |
The minimum amount of products that the customer must purchase to qualify for the premium. Note that this is based on the price of the product as it is in the basket, and so may be influenced by Price Groups.
This allows you to limit which products count toward purchase minimums based on categories.
| Options | |
| None |
Products in all categories count towards purchase minimums. |
| Products in Categories in Trigger List |
Only products included in the Categories listed on the Trigger Categories tab count towards minimums. |
| Products NOT in Categories in Trigger List |
Only products NOT included in the Categories listed on the Trigger Categories tab count towards minimums. |
This allows you to limit which products count toward purchase minimums. Product settings override category settings where there is a conflict.
| Options | |
| None |
All product count towards purchase minimums (unless excluded by category ). |
| Products in Trigger List |
Only products listed on the Trigger Products tab count towards minimums. These will be in addition to those products selected due to category settings. |
| All Products in Trigger List |
Only products listed on the Trigger Products tab count towards minimums, and at least one of each product must be purchased. These will be in addition to those products selected due to category settings. |
| Products NOT in Trigger List |
Products listed on the Trigger Products tab do NOT count towards minimums. |
The promotion will not be applied prior to the date and time entered.
The promotion will not be applied after the date and time entered.
This specifies what the customer gets if they qualify for the promotion.
| Options | |
| Discount Amount |
The customer gets a flat discount amount, for example $5. The amount is specified below. |
| Discount Percent |
The customer gets a percentage discount, for example 15%. The amount is specified below. |
| Cheapest Free |
The customer gets the cheapest product free. This is implemented by giving the customer a discount equal to the price of the product. |
| Free Shipping |
The customer gets free shipping. This is implemented by giving the customer a discount equal to the cost of shipping. |
The amount of the discount the customer receives. It only applies if discount amount or percent are selected above.
What the discount is applied to
If the premium is a discount amount, it will be limited in total value to the total price of the indicated products.
If the premium is a discount percent, it will be calculated as a a percent of the indicated products.
If the premium is a free product, it will be the cheapest of the indicated products.
This setting has no effect on free shipping.
| Options | |
| Entire Order |
The discount is applied to the entire order. |
| All Products |
The discount is applied to all the products in the basket, but not to shipping, tax, or other basket charges. |
| Qualifying Products [products that triggered discount] |
The discount is applied to the same products that were counted to determine if minimum purchase was met. |
| Other Selected Products / Categories |
The discount applies to a set of products as specified below. |
Limits which products the discount applies to based on category. This setting only applies if "Other Selected Products / Categories" was select above.
| Options | |
| None |
Discount is not limited by category |
| Products in Categories in Premium List |
The Discount is limited to products in the categories listed on the Premium Categories List. |
| Products NOT in Categories in Premium List |
The Discount is limited to products not in the categories listed on the Premium Categories List. |
Limits which products the discount applies to. This setting only applies if "Other Selected Products / Categories" was select above.
| Options | |
| None | |
| Products in Premium List | |
| Products NOT in Premium List | |
If this box is checked, then the customer will receive premium multiple times if they meet the requirements multiple times.
For Example: If your trigger is buy 5 videos and your premium is get one free, setting this option would mean that if the customer buys 10 videos they get 2 free.
This option has no effect on free shipping, but does apply to percent discounts.
The total maximum value of discount that this promotion can generate in a single use. For example, you could give 10% off the entire order, with a total limit of $100.
If this box is checked, the a message is generated when the customer enters a promotion or coupon code that is valid, but that they don't qualify for currently.
The message generated when the customer enters a promotion or coupon code that is valid, but that they don't qualify for currently. For example; this message would be generated if the customer entered a promotion code that gave them free shipping on orders of $100 or more, but had not yet placed $100 worth of products in their basket.
This message only appears if the above box is checked. If this message is blank, the default from the main Settings tab is used.
Lists Trigger Product records.
Check one or more boxes in the delete column on the left of the list and click the update button at the bottom of the list to delete the selected records.
Click <-prev or next-> in the footer to move backwards or forward a page. Enter a new value in the field label "page" to change the number of records per page.
Lists Trigger Category records.
Check one or more boxes in the delete column on the left of the list and click the update button at the bottom of the list to delete the selected records.
Click <-prev or next-> in the footer to move backwards or forward a page. Enter a new value in the field label "page" to change the number of records per page.
Lists Affiliate records.
Check one or more boxes in the delete column on the left of the list and click the update button at the bottom of the list to delete the selected records.
Click <-prev or next-> in the footer to move backwards or forward a page. Enter a new value in the field label "page" to change the number of records per page.
Lists Premium Product records.
Check one or more boxes in the delete column on the left of the list and click the update button at the bottom of the list to delete the selected records.
Lists Premium Category records.
Check one or more boxes in the delete column on the left of the list and click the update button at the bottom of the list to delete the selected records.
Lists Coupon records.
Click the [add] link on the right side of the header line to add a new record.
Check one or more boxes in the delete column on the left of the list and click the update button at the bottom of the list to delete the selected records.
Click <-prev or next-> in the footer to move backwards or forward a page. Enter a new value in the field label "page" to change the number of records per page.
A prefix that will be applied to all the generated coupon codes. It defaults to the promotion code and a dash.
The length of the randomly generated part of the coupon code. Longer codes are harder for the customer to type, but offer more possible codes and are therefore harder to guess.
The number of coupons that you would like to generate.
Coupon codes are generated randomly, then checked against the database to be sure that the coupon code does not already exist. If it does exist, and new code is generated and checked. The bailout is the number of times the system will do that before giving up and returning an error.
If this is checked, you will be shown a list of the new coupon codes generated.
Lists Screen records.
Click the [add] link on the right side of the header line to add a new record.
Click the [edit] link on the right side of a line to edit the record.
Check one or more boxes in the delete column on the left of the list and click the update button at the bottom of the list to delete the selected records.
Click <-prev or next-> in the footer to move backwards or forward a page. Enter a new value in the field label "page" to change the number of records per page.
View, add or edit Summary Screen record.
text to be displayed at the top of the Summary Screen
Message to be displayed when there are no promotions displayed on the summary screen.
text to be displayed at the bottom of the Summary Screen
View, add or edit Promotion Screen record.
text to be displayed at the top of the Promotion Screen
Message to be displayed when the user has entered no codes.
Determines how the submit button will be displayed on the Promotion Screen
The text that will be displayed on the Submit Button, if it's a text style button.
The image to be displayed as the Submit Button, if it's an image style button.
text to be displayed at the bottom of the Promotion Screen
View, add or edit Offer Screen record.
The message to be displayed at the top of the Offer Screen
Message to be displayed when there are no such coupon or promo.
The message to be displayed at the bottom of the Offer Screen
View, add or edit Screen record.
The Miva Merchant action code for the action you want to intercept to display this screen, or an arbitrary code to use. Interception occurs after the indicated action. This field is case sensitive, and Miva Merchant action must be in all caps, as shown below:
| ALGI | Affiliate Login |
| UAFL | Affiliate Update |
| IAFL | Affiliate Insert |
| AFPW | Affiliate Email Lost Password |
| LOGN | Customer Login |
| EMPW | Customer Email Lost Password |
| UCST | Customer Update |
| ICST | Customer Insert |
| ADPR | Add Product To Basket |
| AUPR | Add Upsold Product To Basket |
| QNTY | Update Quantity |
| RPRD | Remove Product From Basket |
| ORDR | Save Order Information |
| CTAX | CalculateTax |
| SHIP | Calculate Shipping |
| AUTH | Authorize Payment |
The name of the screen, for your information only.
The header for the screen. It appears before the line where the promotion code is entered.
The prompt for the promotion code.
Determines how the submit button will be displayed on this Screen
The text that will be displayed on the Submit Button, if it's a text style button.
The image to be displayed as the Submit Button, if it's an image style button.
Check this box if you want the screen to redisplay when a promotion code is entered, allowing the customer to enter another code.
Check this box if you want to display a checkbox asking the customer if they have another promotion code to enter.
If this box is checked, then "Request additional code if code entered" becomes the default value of this box.
The text to appear after the above checkbox if it is displayed to the user.
The footer for the screen. It appears after the line where the promotion code is entered.
Enter licensing information here. Please note that once you have entered your license information this tab will no longer be visible.
Enter the license number that you were issued when you purchased this software.
Check this box if you have read and and agree to the EULA. You must agree to the EULA to use this software.