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. You manage your rules in the Store Price Rule CP 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 rule keeps the site, code, members, roles and usage of the discount, so a single-use code that was already used stays used. 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:

1. Buy X Get Y Free: the free products of every valid Buy X Get Y Free rule are added to the cart.
2. Product rules: the price of each cart item is lowered by the matching product rules.
3. Cart rules: the cart rules calculate the cart discount and free shipping.
4. Coupon code check: when the coupon code in the cart no longer matches a valid rule, it is removed from the cart.
5. 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), and the members or roles (of the logged in member)
• 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 rule of each type is 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.

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 Minimum Cart Quantity is the total number of items in the cart, free items included.
• {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:

{cart:items}
    {cart:price:formatted}
    {if cart:on_sale}&nbsp;<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.

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:

{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 and is within its start and end date. Upper and lower case don't matter (SUMMER and summer are 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.
• A code belongs to one rule, and a cart can hold one code at a time.

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 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
• 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

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 and moved Store discounts whose code was already used.
• Coupon code disappears: the code is removed when no rule with that code is valid for the cart (see Coupon codes). Every form that posts to the cart also saves the coupon field: when a form (for example an extra update form) has no coupon code field, the code is removed. Add the field (it can be hidden) to every cart form.
• 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: for an item that already has a sale price, the old price shows the sale price, not the original 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, see the log. Change the code and enable the rule.
• Discounts gone after uninstalling: all rules are deleted on uninstall (see Uninstalling).