10 min read • Updated 3 months ago
Coupon Codes
Unlike product or category quantity discounts, coupon codes apply one single discount as a line-item in the cart, and do not affect the individual product prices. Coupon codes also can apply to one or many categories, but cannot be product-specific (unless the product is the only product in a given category).
The default discount type for coupons is single.
How are they created
Coupons are created from within your store's FoxyCart administration, on the coupons page.
How are they added to an order
Coupons can be added in two ways.
Automatically
Coupons can be added with a product add to cart link or form by specifying the coupon parameter with the coupon's code as the value (after you've created the coupon in the admin). Multiple coupon codes can be added at one time, separated by a comma, for example: coupon=code1,code2,code3. This means that the customer won't need to take any action for the coupons to be applied, and will appear in their cart when the order matches the coupons requirements.
Here are examples for both link and form add-to-cart types. I've created a coupon in the admin with a code of 20OFF20 that gives a bulk 20% discount when a customer orders 20 or more products.
Link Example
<a href="https://YOURSTORE.foxycart.com/cart?name=Flute+Swab&price=10&coupon=20OFF20">
Add to Cart
</a>Form Example
<form action="https://YOURSTORE.foxycart.com/cart" method="post">
<input="hidden" name="name" value="Flute Swab" />
<input="hidden" name="price" value=10 />
<input="hidden" name="coupon" value="20OFF20" />
<input type="submit" value="Buy It!" />
</form>If making use of the add to cart link and form encryption - the coupon parameter does not need to be encrypted.
Manually
A customer can enter a coupon manually on the cart page of the FoxyCart checkout process. If a valid coupon exists for the store, a link to 'Add a coupon' will appear within the carts totals area between the subtotal and the total. Clicking this link will display a text input that customers can enter the code into and click to update the cart and add the coupon.
Something to note here is that if there is currently no valid coupon for the store, then the 'Add a coupon' functionality won't be displayed in the cart. This prevents possible cart abandonment as people may possibly leave your store in search of a coupon that doesn't exist. There are a couple ways that a coupon may not be valid or active:
The current date is outside of the active date range set for the coupon
The coupon has been used as many times as is allowed
How are they displayed
A coupon is displayed as a line item in the totals section of the cart as a single discount amount.
Details
Coupon codes have a variety of configuration options in addition to the discounting functionality described above.
| Coupon Name | The name displayed in the cart, once a coupon has been added. For example, “Loyal Customer 20% Off Coupon”. This allows both the customer and store admin to easily see what coupon has been applied to their cart. |
|---|---|
| Coupon Code | This is the “coupon” itself; the actual text that is distributed by the merchant and entered by the customer. Codes can include letters and numbers, as well as -, _ and ., to a maximum of 50 characters, but care should be taken to ensure it's easily readable (ie. 0 versus O, 1 versus l (lowercase L) versus I (uppercase i), etc.). Coupon codes are case insensitive, so MyCoupon1, MYCOUPON1 and mycoupon1 are all considered the same. |
| Coupon Variations | FoxyCart allows for a single coupon code to be defined, but to generate multiple distinct coupon variations (up to 100 at a time). This allows for easy creation of multiple unique codes, all with identical discount options, which can be very useful for mail merges or other coupon distribution where any individual coupon code may only have 1 single use, but you may need dozens or hundreds (or thousands). |
| Coupon Type | The type of discount you want to apply (see above for details on that) |
| Coupon Details | The discount logic, such as incremental|1-5|2-10 |
| Combinable | If the “combinable” checkbox is left unchecked when creating a coupon it will not be added to the cart if another coupon is already in the cart. Similarly, if this coupon is added first, no other coupons will be able to be added to the cart. Note: The discounts that coupons generate are based off the product subtotal, and other coupons don't impact the generated discount. For instance, if you have a $100 transaction with both a $20 and a 10% off coupon, the order total will be $70 (and not $72, as would be the case if the % discount calculated after the $-discount. |
| Shared Codes Allowed? | If checked, this option allows codes from this coupon to be shared with other coupons on the store. This can allow a single code added to the cart to add multiple different coupons at the same time. The combinable checkbox will be ignored for coupons that have shared codes enabled and also share the same code that is being added. All other validations will apply as normal though. If at least one of the coupons linked to the shared code is added, then any that generate an error will fail silently, just adding those coupons to the cart that were successful. If all coupons from the shared code fail though, then the errors will be displayed. Codes that are shared with other coupons will include a [s] note next to the code in the admin summary for the coupon. Hovering over that note will show the names of the coupon(s) that this code is shared with. Note that shared coupons are handled slightly differently in the cart JSON object, as an array of coupons linked to the coupon code. Review the structure on the template view data for details on how it looks. |
| Multiple Codes Allowed? | If this checkbox is checked, then multiple codes from the current coupon can be added to the cart at the same time. If unchecked, an error will be returned if attempting to add a code that belongs to a coupon that is already present on the cart. |
| Taxable | If the “taxable” checkbox is checked when creating the coupon taxes will be applied before the coupon's discount is applied. Check with your tax professional if you have questions about how you should calculate taxes. |
| Category Discounts | If this box is checked, category discounts will not be applied to the relevant parts of an order (and the coupon discount will be applied instead). As an example, let's say you have a 15% quantity discount (when quantity is 2 or greater) applied for category=shirts, and you have 3 shirts in the cart at $10 each. This quantity discount would be $4.50. Now let's say you have a coupon code with this checkbox checked. When that coupon is added to the cart, the quantity discount will be removed, and only the coupon discount will remain. This is most often useful in situations where you do not want coupons discounts to be added together with other discounts. |
| Line Item Discounts | This is nearly identical to the “Category Discounts” above, but applies to product-level discounts. |
| Valid Dates | If the coupon has dates set, it can only be used within those date ranges. The start and end dates are inclusive, so coupon codes can be used on the start and end dates as well. See notes |
| Apply to Categories | Similar to the category quantity discounts, but can be applied to multiple or all categories. So if a coupon code only applies to the T-Shirt category and there are no T-Shirts in the cart, no discount will be applied. |
| Restrict Usage by Product Code | If you want to limit which products can use this coupon, you can enter a comma separated listed of product codes or partial product codes using * as a wild card at the beginning and/or end of the value. So abc123, fun_*, *-small would match abc123, fun_ and fun_times, and example-small. It wouldn't match abc12, abc1234, fun, or good-smalls. If a code starts with - it will be considered as a block instead, matching everything except products that match that code. For example -*-small would match every product that does not have a code that ends in -small. Allow lists and block lists can also be combined, foo*, -foobar would match all products that begin with foo except any products with a code of foobar. Currently restricted to a maximum length of 5000 characters. |
| Restrict by Item Options | You may have arbitrary item options (like brand, publisher, size, location, etc.) that determine what type of discount to apply. Using this setting, you can restrict coupons using similar logic as the “restrict usage by product code” above. Instead of a single comma-separated list of values to match against, input here is per item option. Wildcards can be used in option values but not option names. The functionality is only available in the new admin and via the API. Though not technically item options, the following native item values can also be matched against: name, parent_code, url, image, sub_frequency. |
| # of Uses (Total) | If you want to limit the number of uses this coupon as a whole can be used, enter a number here. If, for example, only the first 50 customers can use the coupon, enter 50 here. This relates to coupon variants and the number of uses per code (below). If you have 1 coupon code and 10 uses, the coupon will not be able to be used after 10 successful transactions. If you have 1 coupon with 100 variants but only 50 uses, only the first 50 uses will be allowed, regardless of the number of uses per code. |
| # of Uses (Per Code) | This is similar to the total number of uses, but only limits individual coupon code variants. So if you have 100 coupon code variants and this value is set to 1, each variant will only be able to be used once. The total uses allowed (above) is a higher priority than this, however, so if a coupon's total uses has already been reached then this value doesn't matter. |
| # of Uses (Per Code Per Customer) | If you want to limit the number of uses an individual customer can use each code for a given coupon, enter the number of uses here. For example, if each customer is only allowed to use each of the coupon's codes once, enter 1. This is based off of the customer's email address, not a payment method, ip address, shipping address or browser cookie, so the customer could conceivably enter a different email address to receive the discount again. |
For the three options that limit a coupon based on usage (either in total, or by code or customer), a coupon is only considered used if it applies an actual discount on the transaction. This means for subscriptions that have a future start date, making their initial transaction $0, that won't count towards the usage for a coupon.
Selling subscriptions with the PayPal Express Checkout (Legacy) integration? Limitations on changes that are possible to subscriptions managed by PayPal mean that coupons that only apply for a certain number of uses (either by dates or number of uses for the coupon, code or customer) won't behave as expected for legacy PayPal subscriptions. While the coupon will be removed within Foxy, the customer will continue to be charged the discounted amount by PayPal as they were from their first charge. We don't recommend utilising limited usage coupons with PayPal Express Checkout (Legacy) based subscriptions.