Appearance
How does it work
Store Price Rule adds discount rules to Reinos Store: cart discounts, product discounts, free shipping and Buy X Get Y Free promotions. It has no template tags of its own. You keep using the regular Store tags and variables (see the Cart tag), and the discounts show up in them automatically.
What changes in the Store module
When Store Price Rule is installed, it replaces the discount system of the Store module:
- Discount page: the Discount item disappears from the Store CP sidebar, and the old URL of the page goes to the Store Price Rule CP. You manage your rules there instead (see the CP Overview).
- Discount settings: the Discount settings section ("Enable Stacking Discounts") disappears from the Store settings. You can find the same setting in the settings of this module.
- Existing discounts are moved over: when you open the Store Price Rule CP, your existing Store discounts are turned into cart rules and removed from the Store module. A discount for reorders becomes a product rule with Only reorders and renewals, so it only discounts the reordered products, like in the Store. The Store only used the oldest discount for reorders of a site that has not expired; when there are more, only that one stays enabled, the others are disabled and logged, because rules can add up. A rule keeps the site, code, members, roles and usage of the discount, so a single-use code that was already used stays used. A discount for reorders gets no usage limit, because in the Store single use only applies to codes. When the code is already used by another rule, the new rule is disabled and an error is logged: give it another code and enable it.
- Discounts in the cart: cart discounts, product prices, free shipping and the coupon code are handled by Store Price Rule. The "Free shipping above" setting of the Store module keeps working next to your free shipping rules.
- Orders: the rules used in an order are shown in the order details in the Store CP, with their type, value and code.
- Global variable:
{reinos_store_price_rule_module_installed}is true (see the global variables of the Store module).
Uninstalling
When you uninstall Store Price Rule, all price rules and logs are deleted. They are not turned back into Store discounts. The Discount page and the discount settings come back in the Store module, which uses its own (now empty) discount system again. The discounts already saved with existing orders are kept. Free items that are still in a customer's cart stay there with a price of 0 until the cart is emptied.
The flow of a cart load
The rules are checked every time the cart is shown or updated (for example by the Cart tag or at checkout), in this order:
- Buy X Get Y Free: the free products of every valid Buy X Get Y Free rule are added to the cart (with stacking disabled only those of the first matching rule).
- Product rules: the price of each cart item is lowered by the matching product rules.
- Cart rules: the cart rules calculate the cart discount and free shipping.
- Coupon code check: when the coupon code in the cart no longer matches a valid rule, it is removed from the cart.
- Checkout: when the order is placed, the rules used are saved with the order and count towards the usage limits.
Rule Processing
A rule is applied when:
- the rule is active and today falls between its start and end date (when set)
- the customer entered the code of the rule (only for rules that are triggered by a code)
- its conditions are met: minimum cart total, minimum quantity, Entry IDs (for a product rule: the cart item is one of the products, for the other rules: at least one of the products is in the cart, the free products of Buy X Get Y Free rules don't count), and the members or roles (of the logged in member)
- with Only reorders and renewals: for a product rule, the cart item reorders or renews a paid earlier order of the customer; for the other rules, such an item is in the cart. Usage Limit Per Reorder and Only up to the ordered quantity are checked here too
- its usage limits have not been reached
The rules are checked per group (Buy X Get Y Free rules, product rules and cart rules), in the order of the overview: top to bottom, as set with the up and down arrows.
With stacking discounts enabled, every matching rule is applied on top of the previous one (a percentage is taken from what is left). With stacking disabled, only the first matching cart rule, the first matching product rule (per cart item) and the first matching Buy X Get Y Free rule are applied. A free shipping rule counts as a match too, so with stacking disabled no cart discount is applied after a matching free shipping rule. A Buy X Get Y Free rule counts as a match when at least one of its free products is added (a product that is out of stock is skipped).
Cart Rules Integration
Cart rules (cart percentage, cart fixed and free shipping) use the existing discount variables of the Store module, so they appear in your templates without any changes:
- Cart discount: the total discount of all cart rules is shown as
{cart:discount}(see cart:discount). The discount is calculated on the subtotal excluding tax, so a fixed discount of 10 is 10 excluding tax. - Free shipping: a free shipping rule sets the shipping costs to 0, and
{cart:has_free_shipping}(or{order:has_free_shipping}for orders) is true. - The Minimum Cart Total is compared with the subtotal excluding tax, after the product discounts. The discounts of earlier cart rules don't lower it, so the order of the cart rules doesn't change which rules apply.
- The Minimum Cart Quantity is the total number of items in the cart, without the free products of the Buy X Get Y Free rules.
{cart:discount_ids}holds the IDs of the cart rules that were applied (separated by|).
Product Rules Integration
Product rules (product percentage and product fixed) lower the price of the items in the cart. The discount is taken from the price per item (excluding tax) and the price never goes below 0. The Minimum Product Quantity is the quantity of that item in the cart.
Inside the {cart:items} tag pair, {cart:old_price} holds the price before the discount and {cart:price} the discounted price, so you can show "was/now" prices. Use {cart:on_sale} to check if an item has a discount, and {cart:discount_ids} for the IDs of the product rules applied to that item:
html
{cart:items}
{cart:price:formatted}
{if cart:on_sale} <strike>{cart:old_price:formatted}</strike>{/if}
{/cart:items}When a product rule has Entry IDs, only the cart items of those products get the discount. With Only reorders and renewals, only the cart items that reorder or renew an earlier ordered product (added with the reorder tag) get the discount.
Buy X Get Y Free Integration
A Buy X Get Y Free rule adds the free product to the cart automatically, with a quantity of 1 (the customer can't change it) and a price of 0. Its normal price is shown as the old price. The name, price and SKU come from the fields set in the channel settings of the Store module.
The free product is checked every time the cart is loaded: it is added once and stays in the cart while the rule applies. When the conditions are no longer met (for example the customer removes the product they had to buy), the free product is removed as well. A cart with only free products is emptied, so a visitor without products in the cart gets nothing. When the free product is already in the cart as a normal item, the free product is added as a separate item and the normal item keeps its price.
Use {cart:added_by_buy_x_get_y_free} inside the {cart:items} tag pair to recognise free items:
html
{cart:items}
{cart:name}
{if cart:added_by_buy_x_get_y_free}<small>Free gift</small>{/if}
{/cart:items}Coupon codes
A rule that is triggered by a code is applied when the customer enters that code in the coupon code field of the cart form (<input type="text" name="coupon_code" value="{cart:coupon_code}"/>, see cart:discount).
- The code is accepted when a rule with that code exists, is active, is within its start and end date and its usage limits are not reached. Upper and lower case don't matter (
SUMMERandsummerare the same code). Otherwise it is not saved, and a code entered earlier is removed. - After that, the other conditions are checked every time the cart is loaded. When they are not met (for example the minimum cart total is not reached, or the usage limit is reached), the code is removed from the cart and the customer has to enter it again.
- Available from v2.0.0: why a code gives no discount is shown with
{cart:coupon_code_error}:usedwhen a usage limit of the rule is reached,invalidotherwise (an unknown or expired code, or a condition that is not met). - With stacking disabled, the code is also removed when an earlier rule of the same group (for example an automatic cart rule above the code rule) already matched, because the rules after the first match are not checked.
- A cart can hold one code at a time, and every rule has its own code (see Code).
Usage limits
A rule counts as used when the order is placed (before payment):
- a rule counts once per order, also a product rule that was applied to more items of the order
- the limits are checked again when the order is placed; when a rule has a usage limit, checkouts at the same moment wait for each other, so a single-use code can't be used by two orders. Available from v2.0.0: when the code of the cart can't be used anymore, the code is removed and the order is not placed: the customer sees
{global_error:coupon_code}and can check the order (see Coupon codes). An automatic rule (without a code) whose limit is reached in the meantime is left off the order without a message. In a checkout with steps, a code that is used up while the customer is on step 2 is removed when step 2 is sent, without{global_error:coupon_code}: the next step shows the totals without the discount and{cart:coupon_code_error}tells the customer why - the Usage Limit Per Member counts the orders of the customer: for a logged in member the orders of that member or with the email address of the cart, for a guest the orders with the email address of the cart. As long as a guest hasn't entered an email address the rule applies; at checkout it is checked again with the entered email address, so the discount can drop off the order then (a rule with a code stops the order, see above)
- orders that are later cancelled, failed, expired or refunded no longer count (the Store marks their usage as obsolete, Reinos Store 4.0.0); an order that stays open or pending without payment keeps counting. The Usage Limit Per Reorder is the exception: an open order, or one that is pending on the review step of a gateway, doesn't count for it, so a customer whose payment failed can try again (see Usage Limit Per Reorder)
- the last order of the customer's own cart doesn't count while it is unpaid and open, or pending on the review step of a gateway: when the customer checks out again from the same cart (e.g. after a payment error or after coming back from the payment page), the Store fails that order first and releases its codes (Reinos Store 4.0.0), so the customer keeps a single-use or per-member code. An open order of another cart (e.g. another browser) keeps counting until it is cancelled or expires
A Buy X Get Y Free rule counts once per order with its free product. When its usage limit is reached, the free product is removed from the cart.
Common pitfalls
- Discount is not applied: check that the rule is active, the start and end date, the member and role conditions (guests are not logged in members) and the usage limits. With stacking disabled, an earlier matching rule of the same type stops the rest. The log (see the settings) shows free products that are out of stock, moved Store discounts whose code was already used and coupon codes that stopped an order at checkout.
- Coupon code disappears: the code is removed when no rule with that code is valid for the cart, or, with stacking disabled, when an earlier rule of the same group already matched (see Coupon codes). A cart form that posts an empty coupon code field also removes the code; a form without the field keeps it.
- Rules stack while you didn't expect it: check that "Enable Stacking Discounts" is off. Before Store 4.0.0 the rules were stacked as long as the setting had never been saved, even though it showed off.
- Amounts are excluding tax: fixed discounts and the minimum cart total are excluding tax, after the product discounts.
- Product rules on sale items: the discount is taken off the sale price, and the old price (
{cart:old_price}) stays the original price, not the sale price. - Free product is not added: the channel of the free product must be enabled in the channel settings of the Store module, with a price, name and SKU field set. A product without a price, name or SKU, or one that is out of stock, is not added.
- Moved Store discount is disabled: its code was already used by another rule, or it is a discount for reorders while an older one is still valid (the Store only used the oldest), see the log. Change the code, or check whether both discounts for reorders should apply, and enable the rule.
- Discounts gone after uninstalling: all rules are deleted on uninstall (see Uninstalling).
