Mage_CatalogRule is a core module tasked to provide automated catalog price management, which can be controlled by a set of conditions. These conditions define a subset of the catalog to which price rules apply. For each rule a date range can be set, within which the rule is used. Also rules can be set to apply for certain customer groups. Catalog rules are defined on a website level, i.e. if a website has several store views, a website catalog price rule will apply to them all.

The catalog price rule management interface is found in the shop administration back-end under Promotions => Catalog Price Rules. If you are using a test installation with sample data (which you can obtain here), you can already see several catalog rules in the grid. We will discuss one of them as an example. If you don’t have the sample data – you can create sample catalog rules as we go over them.

Actions

Once you have defined the conditions, move on to the last tab, Actions. There you’ll see several settings, which, when combined, tell the system how to change the price when applying the rule.

The first setting is a drop-down list called Apply. It has four options, which are used by the Mage_CatalogRule module’s helper class to calculate the price:

public function calcPriceRule($actionOperator, $ruleAmount, $price)
{
    $priceRule = 0;
    switch ($actionOperator) {
        case 'to_fixed':
            $priceRule = min($ruleAmount, $price);
            break;
        case 'to_percent':
            $priceRule = $price * $ruleAmount / 100;
            break;
        case 'by_fixed':
            $priceRule = max(0, $price - $ruleAmount);
            break;
        case 'by_percent':
            $priceRule = $price * (1 - $ruleAmount / 100);
            break;
    }
    return $priceRule;
}

Thus, each of these options has the following effect:

• To Fixed Amount: the product price is set to the $ruleAmount, or remains unchanged if the original price is less than $ruleAmount. If the original price is $100 and the rule amount is 90, then the resulting price is $90.
• To Percentage of the Original Price: the product price is set as a percentage ($ruleAmount) of the original price. If the original price is $150 and the rule amount is 80 then the resulting price is $120.
• By Fixed Amount: the product price is reduced by $ruleAmount, or set to zero if the subtraction produces a negative value. If the original price is $100 and the rule amount is 15 then the resulting price is $85.
• By Percentage of the Original Price: the product price is set to the subtraction result of the original price and its percentage ($ruleAmount). If the original price is $150 and the rule amount is 15 then the resulting price is $127.5 (150 – (15*150/100))

The value selected in the “Apply” list is translated into the property simple_action of the rule model.

The next input field is Discount amount, whose value is used by the rule’s action when calculating the new price by assigning it to the $ruleAmount variable from the helper function. The input is required and accepts a valid decimal number. Its value is saved in the rule property discount_amount.

The drop-down list Enable Discounts to Subproducts presents you with an option to extend the new price calculation to sub-products, i.e. the child products of configurable products (grouped products also have children, but their price calculation is not affected by this option). Keep in mind that when catalog price rules are applied to the children of a configurable product, it is not the price of the simple product that is modified as the “original price”. Instead the system re-calculates pricing options, which are entered next to simple products in the configurable’s “Associated products” edit tab (we will see this setting in action later when discussing an example of a rule applied to a configurable product).

If you select “Yes” in the “Enable Discounts to Subproducts” drop-down list, two additional inputs will appear, Apply and Discount Amount, which are similar to those of the main rule action. They will be applied in the same manner to the pricing options of the sub-products. These inputs correspond to rule properties sub_simple_action and sub_discount_amount. The option selected in the ”Enable Discounts to Subproducts” list is saved into the sub_is_enable rule property.

The last option in the “Action” tab is Stop Further Rule Processing (rule property stop_rules_processing). As I’ve mentioned before, there may be a situation when multiple rules can be applied to the same product; and the order in which they are applied is defined by the rule property sort_order (defined in the input field “Priority” in the “Rule Information” tab). It is possible to stop the further rule processing by setting this property to yes. Then the rule with the highest priority (actually, with the lowest value in the sort_order property, 0 by default) or with the lowest rule_id is applied while the rest is ignored.

Applying Catalog Rules and Calculating Product Prices

Before catalog rules can have any effect on product prices, they must be applied. The module Mage_CatalogRule has a cronjob that is executed daily. This cronjob goes through all the active catalog rules, finds products that match their conditions and calculates prices for those products. Alternatively, this process can be started from the back-end: “Promotions” => “Catalog Price Rules” => “Apply Rules”. The process of applying rules is relatively complex and uses data from several tables.

The first step is to match products to rules. This task is performed by the rule resource model in method Mage_CatalogRule_Model_Resource_Rule::updateRuleProductData. Here the system calls the rule model’s methods to find products matching the rule’s conditions. Found products are stored together with rule properties in table catalogrule_product, which serves as an information source for further price calculations.

It is important to keep in mind that updating the rule-product relationships in the catalogrule_product table is performed not in a cronjob, but only if you either manually apply rules in the back-end, or a product is saved (including the case when products are imported via the Mage_ImportExport module). The cronjob that applies rules daily by calling Mage_CatalogRule_Model_Observer::dailyCatalogUpdate skips this step and performs price calculations assuming that the rule-product relationships are already present in the database. This actually makes sense: if you create a rule, you must apply it explicitly at least once rather than later find yourself in a situation where a rule was applied automatically without your concern.

With the rule-product matching done, price calculation can start. This task is performed by the rule resource model’s method Mage_CatalogRule_Model_Resource_Rule::applyAllRulesForDateRange($fromDate = null, $toDate = null, $productId = null), and prices affected by rules are saved in table catalogrule_product_price. For each price entry the system saves a validity date in column rule_date. This information is very important because this date is checked every time a price is requested.

Rules can be set active for a certain period of time. To comply with this condition the prices in table catalogrule_product_price are updated daily by a cronjob. The cronjob calls the module’s observer method Mage_CatalogRule_Model_Observer::dailyCatalogUpdate(), which calls the applyAllRulesForDateRange() of the rule’s resource model with no arguments. If you look into this method’s code, you’ll see that if no value is provided for the fromDate and toDate parameters, it is assumed that the prices are calculated for rules, which are valid on the current day from 00:00 to 24:00. Any old data (with rule_date in the past) is deleted. This guarantees that on any given day the table catalogrule_product_price contains prices modified only by those rules, which are active on that day.

As I’ve mentioned above, the prices are calculated for products, whose relationships to rules are defined in table catalogrule_product. This can be seen in the function Mage_CatalogRule_Model_Resource_Rule::_getRuleProductsStmt($fromDate, $toDate, $productId = null, $websiteId = null), which is called before the calculation iterations start:

$select = $read->select()
->from(array('rp' => $this->getTable('catalogrule/rule_product')))
->where($read->quoteInto('rp.from_time = 0 or rp.from_time <= ?', $toDate)
. ' OR ' . $read->quoteInto('rp.to_time = 0 or rp.to_time >= ?', $fromDate))
->order(array('rp.website_id', 'rp.customer_group_id', 'rp.product_id', 'rp.sort_order', 'rp.rule_id'));

This piece of code from the function _getRuleProductsStmt creates a Varien_Db_Select object, which builds a query of all products from table catalogrule_product. Any product, which had not been previously matched to a rule, is not included into the price calculation.

The populating of the catalogrule_product_price is performed for every website and for the date range defined in the applyAllRulesForDateRange function’s call (none of this function’s calls in Magento core supplies a specific range, therefore it is performed for the current day as per default). The data collected in this table is now available to event observers that modify product prices.

Catalog Rule Events and Observers

There are 9 events that the Mage_CatalogRule module reacts to. They can be divided into three categories:

Responses to product price requests. If the system asks for a product price, the observer will return an adjusted price if any of the existing rules apply. This group includes three events:

1. catalog_product_get_final_price – this event is dispatched when a product type model’s method getFinalPrice is called. If the call takes place in the front-end, the observer reacts with its method Mage_CatalogRule_Model_Observer::processFrontFinalPrice. If the call is made from the back-end, the observer executes Mage_CatalogRule_Model_Observer::processAdminFinalPrice. The difference between the two methods lies in the fact that price rules can contain conditions that apply only in a specific website or to a certain customer group or groups. When processing a front-end request this information is obtained from the event details or from the customer session. In the back-end this data is extracted from the rule and product objects. Other than that, the process in both methods is similar – the rule resource model is tasked to fetch an adjusted price from the catalogrule_product_price table. Note that if the adjusted price is higher than the product’s current final price, the lower price is returned, i.e. the current final price remains unchanged.
2. catalog_product_type_configurable_price – this event is dispatched when the system needs to calculate option prices for a configurable product. This happens either in the block class Mage_Catalog_Block_Product_View_Type_Configurable‘s method getJsonConfig() or in price model method Mage_Catalog_Model_Product_Type_Configurable_Price::getTotalConfigurableItemsPrice. In both cases a request for a price of an option of a configurable product is intercepted and the price is modified according to applicable catalog rules. We will discuss this process in an example later.
3. prepare_catalog_product_collection_prices – this event is dispathed whenever the system must evaluate prices of products in a collection that is a part of a checkout quote or of a bundle product. If you search for this event’s name in the code, you’ll find that it is dispatched in two methods: Mage_Sales_Model_Resource_Quote_Item_Collection::_assignProducts and Mage_Bundle_Model_Product_Price::getTotalBundleItemsPrice. The event triggers the Mage_CatalogRule module’s observer method prepareCatalogProductCollectionPrices. This method goes through the collection’s products and fetches their rule-adjusted prices. The collection, however, is not modified. The prices are saved in the observer’s internal property _rulePrices, which becomes available to other event calls within the current request since the observer instantiated as a singleton. Note that quotes collect their item prices by calling methods of the price models of the underlying products, e.g. Mage_Catalog_Model_Product_Type_Price or Mage_Catalog_Model_Product_Type_Configurable_Price, and it is there where the events that modify prices are triggered.

The next group of events is Reactions to product data changes. These reactions include creating, importing, modifying products, and re-indexing products prices. In these cases the observer rebuilds product-rule relationships, re-populates the catalogrule_product_price table, and supplies adjusted prices to be included into the price index. The events are:

1. catalog_product_save_after – whenever a product model is saved, Magento dispatches this standard event, which triggers the Mage_CatalogRule module’s observer method applyAllRulesOnProduct. This method engages the rule model and the rule resource model to generate relationships between the given product and all the rules in the system. After these matches have been found and saved in table catalogrule_product the system calculates adjusted prices for the product on the current day and saves them in table catalogrule_product_prices.
2. The events catalog_product_import_finish_before and catalog_product_import_after do a similiar job for products imported via module Mage_ImportExport. The first event triggers a method that creates product-rule relationships, and the second one starts a process of applying rules to the imported products’ prices.
3. prepare_catalog_product_price_index_table – this event is dispatched during the product price re-indexing process. After the indexed price is saved into the index table this events triggers an observer method, which updates the index table with catalog rule adjusted prices. Because of this fact it is important to make sure that the Mage_CatalogRule module’s cronjob, which calculates rule prices for the current day, is run before the daily product price indexer.

<jobs>
    <catalogrule_apply_all>
        <schedule>
            <cron_expr>0 1 * * *</cron_expr>
        </schedule>
        <run>
            <model>catalogrule/observer::dailyCatalogUpdate</model>
        </run>
    </catalogrule_apply_all>
</jobs>

As you can see from the snippet of the catalog rule module’s config.xml, the job runs every day at 1AM. The standard cron schedule for the product price indexing is 2AM, as defined in the Mage_Catalog module’s configuration:

<jobs>
    <catalog_product_index_price_reindex_all>
        <schedule>
            <cron_expr>0 2 * * *</cron_expr>
        </schedule>
        <run>
            <model>catalog/observer::reindexProductPrices</model>
        </run>
    </catalog_product_index_price_reindex_all>
</jobs>

Reactions to attribute model changes. This last event group is comprised of events that react to changes in attribute model data. If an attribute, which is already in use by a catalog rule, is changed in any way preventing it from being used by that catalog rule, the rule can no longer apply to product prices. The events are:

1. catalog_entity_attribute_delete_after – deleting attributes, obviously, invalidates the rules that use them. Once an attribute is deleted, the system checks if it is employed in conditions of any rule. If such rule is found, the attribute is removed from its conditions, the rule is deactivated, and all the rules are applied again to invalidate any prices modified by that rule.
2. catalog_entity_attribute_save_after – the system checks if the edited attribute still can be used for the rule, i.e. its property is_used_for_promo_rules is set to 1. If not, then the process is the same as when dealing with deleted attributes: remove the attribute from rule conditions, deactivate affected rules, re-apply all active rules.

Catalog Price Rules and Configurable Products

Before concluding the discussion on catalog price rules, let’s consider an example that should help us to understand how catalog rules are employed and what their effect is. I choose a configurable product for this demonstration, which will also make possible to get an insight into how option prices of configurable products are modified by the catalog rules.

Prices for configurable products are processed on two levels. First, a final price of the configurable product is requested and adjusted as the module’s observer reacts to the catalog_product_get_final_price event. The second level is the pricing options of the configurable product. The configurable options are comprised of sub-products. If there is a price set on a configurable option, it can be controlled by a price rule. Such price rule has to have its property ‘sub_is_enable“ active. The observer’s function responsible for applying catalog rules to configurable option prices is called Mage_CatalogRule::catalogProductTypeConfigurablePrice(Varien_Event_Observer $observer). To illustrate this let’s create a test rule and apply it to a configurable product. If you are using the sample data provided by Magento, look for a product with SKU ‘ecco’. This is a configurable product and it has a configurable attribute ‘size’ with 4 options: sizes 3, 4, 5, and 6. These options are represented by simple products with SKUs ‘ecco_3’, ‘ecco_4’, ‘ecco_5’, and ‘ecco_6’. Note that fields “Price” next to each option are empty, which means that no matter what option a customer selects, the price remains the same $159.99. This is how the product and its options look in the back-end:

And this is how the product is presented in the front-end:

Now, let’s create a rule to apply to this product. In the “Promotions” => “Catalog Price Rule” click on “Add New Rule” and enter the following values in the rules properties in the “Rule Information” tab:

• Rule Name: “20% off ECCO”
• Status: “Active”
• Websites: select all
• Customer Groups: select all
• From Date and To Date: leave empty.
• Priority: -1

In the tab “Conditions” set up the following: If ALL of these conditions are TRUE: SKU is ecco.

In the tab “Actions” choose “By Percentage of the Original Price” in the “Apply” list. Enter 20 into the “Discount Amount” field. Set “Enable Discount to Subproducts” to “Yes”, in the next “Apply” list select again “By Percentage of the Original Price” and enter 20 into the “Discount Amount” field. In the last list, “Stop Further Rule Processing” select “Yes”.

Click “Save and Apply”. Once the rule is applied, refresh the cache and reload the product page. You’ll notice that the old price of $159.99 now has a strike through and a “special price” of $127.99 is displayed below. However, when you select an option, the price does not change. The reason for that are missing option prices in the configurable product.

As I’ve mentioned before, catalog rules are applied to option prices and not to the actual prices of sub-products. Let’s now add option prices to the configurable product. In the back-end, in tab “Associated Products” fill “Price” input fields of the “Shoe Size” options with the following values:

• Option 3: 100
• Option 4: 110
• Option 5: 120
• Option 6: 130

Leave the values in the drop-down list next to them set to “Fixed”. These setting means that whenever one of the shoe size options is selected, the base price of the product is increased by the option price. For example, if a customer selects size 4, the total price would be $(159 .99+ 110) = $269.99. So it is, of course, if no catalog price rule is applied. To observe the effect of a catalog price rule on our configurable product, save your changes, clear the cache, and reload the product page. You do not need to re-index prices or to re-apply catalog rule in this case – saving a product will trigger the Mage_CatalogRule module’s observer to do it automatically.

Now, in the product page you’ll see that the product option drop-down list contains option price information. Next to every option there is a number showing how the price will change if the option is selected. When no option is selected, the option list looks like this:

• 3: +$80.00
• 4: +$88.00
• 5: +$96.00
• 6: +$104.00

These values are equal 80% of the option prices we’ve entered into the configurable product. Select option 4 and the total price of the product changes to $215.99, which is 80% of the price of $269.99 for the same option without the catalog rule effect.

We have covered an important topic of the catalog price rules in detail, I believe, sufficient for you to understand an correctly employ them. This function is quite powerful and can be used for almost any task that requires product price manipulations. If you need something more, for instance, an ability to adjust prices according to, say, a session flag set when a visitor arrives via a link in a newsletter promising action prices – feel free to write an extension of the Mage_CatalogRule module to implement this or any other functionality you need.