Product Relationship Rules v26.1+

Product Relationship Rules in Maho enable you to automatically manage Related Products, Up-sells, and Cross-sells based on powerful, condition-based rules. Instead of manually assigning product relationships one by one, define rule-based criteria to dynamically generate these links across your entire catalog.

Overview

Product Relationship Rules automate the tedious process of manually linking products, allowing you to:

• Automate product linking: Automatically generate related, up-sell, and cross-sell relationships
• Rule-based conditions: Use sophisticated product attribute matching with source and target conditions
• Priority system: Control which rules take precedence when multiple rules apply
• Smart sorting: Order linked products by price, name, date, or random
• Flexible matching: Include a special "Source Match" condition to link products with matching attributes
• Performance optimized: Batch processing with configurable cron scheduling
• Per-type rules: Create separate rules for related, up-sell, and cross-sell products

Key Benefits

For Merchandisers

• Time savings: Set up rules once instead of manually linking thousands of products
• Consistency: Ensure all products follow the same relationship logic
• Merchandising strategy: Implement sophisticated cross-selling strategies at scale
• Dynamic updates: Product relationships automatically update as catalog changes
• A/B testing: Test different relationship strategies with priority-based rules

For E-commerce Managers

• Revenue optimization: Maximize cross-sell and up-sell opportunities
• Inventory management: Promote complementary or alternative products automatically
• Category-based targeting: Link products within or across categories
• Seasonal campaigns: Use date ranges to activate promotional relationships
• Performance insights: Consistent rule-based relationships enable better analytics

For Business Owners

• Increased AOV: Strategic product relationships drive higher average order values
• Reduced manual work: Eliminate hours of tedious product relationship management
• Scalability: Handle catalogs of any size without manual intervention
• Competitive advantage: Enterprise-level merchandising automation
• Flexibility: Adapt relationship strategies quickly as business needs change

How It Works

Product Relationship Rules operate on a two-stage matching system:

1. Source Product Conditions: Define which products should have relationships (e.g., "All products in the Electronics category")
2. Target Product Conditions: Define which products should be linked to the source products (e.g., "Products in the Accessories category")

Special Feature: Source Match Conditions

The unique Source Match condition in target conditions allows you to link products that share attributes with the source product. For example:

• Link products in the same category as the source product
• Link products with the same manufacturer as the source product
• Link products with the same color as the source product
• Link products with matching custom attributes

This powerful feature enables context-aware product relationships that adapt to each product's specific attributes.

Products That a Rule Never Links

A rule links only products that the storefront can show. It skips a target product when:

• the product is disabled
• the visibility of the product is not "Catalog" or "Catalog, Search"
• the product is not in a website of the source product

So Maximum Links counts only products that the customer can see. A source product that is in no website gets no links.

A rule does not check the stock, because a store can sell out-of-stock products, for example on backorder. To link only products that are in stock, add the target condition Stock Status is "In Stock". The condition reads the same stock status as the storefront, so a configurable product is out of stock when all its children are. In a store with several websites, a product is "In Stock" when it is in stock in one of its websites. The rule checks this condition when it runs. A product that comes back in stock gets its links on the next run.

The storefront also hides some out-of-stock products:

• The cart never shows a cross-sell that is out of stock.
• The product page hides out-of-stock related products and up-sells when System > Configuration > Catalog > Inventory > Stock Options > Display Out of Stock Products is "No".

Rule Components

Basic Information

Link Types

Maho supports three types of product relationships:

Sort Orders

Control how linked products are ordered:

Priority System

When multiple rules could apply to a product:

1. Rules are evaluated in order of priority (lowest number first)
2. The first matching rule for each product wins
3. Only one rule per product per link type is applied
4. Higher priority rules override lower priority rules

Example: - Rule A (Priority 10): Links all "T-Shirts" to "Jeans" - Rule B (Priority 20): Links all "Blue T-Shirts" to "Shorts" - Result: Blue T-Shirts get linked to Jeans (Rule A wins due to lower priority number)

Source Product Conditions

Define which products should receive relationship links using standard product attribute conditions:

Common Condition Types

## Target Product Conditions

Define which products should be linked to the matched source products using the same condition types PLUS the special Source Match condition:

Standard Conditions

All the same condition types as Source Product Conditions apply here (Category, Price, SKU, etc.)

Source Match Condition

The Source Match condition creates context-aware relationships by matching target products to source product attributes:

Example - Same Category Related Products:

Source Conditions:
  - Category is "Clothing/T-Shirts"

Target Conditions:
  IF ALL of these conditions are TRUE:
    - Category (Source Match) matches source
    - Type is "Simple"
    - Stock Status is "In Stock"

Result: Each T-shirt gets related to other T-shirts in the same category

Example - Cross-Category Up-sells:

Source Conditions:
  - Category is "Electronics/Cameras"
  - Price is less than 1000

Target Conditions:
  IF ALL of these conditions are TRUE:
    - Category is "Electronics/Cameras"
    - Price is greater than source product price
    - Stock Status is "In Stock"

Result: Each camera gets up-sold to more expensive cameras

Rule Examples

Example 1: Same-Category Related Products

Goal: Show other products from the same category as related products

Configuration: - Name: "Related: Same Category Products" - Status: Active - Link Type: Related Products - Priority: 10 - Sort Order: Random - Max Links: 6

Source Conditions:

IF ALL of these conditions are TRUE:
  - Status is "Enabled"
  - Visibility is "Catalog, Search"

Target Conditions:

IF ALL of these conditions are TRUE:
  - Category (Source Match) matches source
  - Stock Status is "In Stock"

Example 2: Brand-Specific Up-sells

Goal: Up-sell higher-priced products from the same manufacturer

Configuration: - Name: "Up-sell: Same Brand Premium" - Status: Active - Link Type: Up-sell Products - Priority: 20 - Sort Order: Price: Low to High - Max Links: 4

Source Conditions:

IF ALL of these conditions are TRUE:
  - Type is "Simple"
  - Price is less than 500

Target Conditions:

IF ALL of these conditions are TRUE:
  - Manufacturer (Source Match) matches source
  - Price is greater than source product price
  - Stock Status is "In Stock"

Example 3: Accessory Cross-sells

Goal: Cross-sell accessories from a specific category

Configuration: - Name: "Cross-sell: Camera Accessories" - Status: Active - Link Type: Cross-sell Products - Priority: 15 - Sort Order: Price: Low to High - Max Links: 8

Source Conditions:

IF ALL of these conditions are TRUE:
  - Category is "Electronics/Cameras"
  - Status is "Enabled"

Target Conditions:

IF ALL of these conditions are TRUE:
  - Category is "Electronics/Camera Accessories"
  - Stock Status is "In Stock"
  - Price is less than 100

Example 4: Seasonal Promotions

Goal: Promote winter accessories with winter clothing

Configuration: - Name: "Related: Winter Accessories" - Status: Active - Link Type: Related Products - Priority: 5 - Sort Order: Newest First - Max Links: 5 - From Date: 2026-11-01 - To Date: 2027-03-31

Source Conditions:

IF ANY of these conditions is TRUE:
  - Category is "Clothing/Winter Coats"
  - Category is "Clothing/Winter Jackets"

Target Conditions:

IF ANY of these conditions is TRUE:
  - Category is "Accessories/Scarves"
  - Category is "Accessories/Gloves"
  - Category is "Accessories/Hats"

Example 5: Matching Color Coordination

Goal: Show products in matching colors as related items

Configuration: - Name: "Related: Matching Colors" - Status: Active - Link Type: Related Products - Priority: 30 - Sort Order: Random - Max Links: 4

Source Conditions:

IF ALL of these conditions are TRUE:
  - Category is "Clothing"
  - Color attribute exists

Target Conditions:

IF ALL of these conditions are TRUE:
  - Category (Source Match) does not match source
  - Color (Source Match) matches source
  - Stock Status is "In Stock"

Admin Interface

Navigate to: Catalog > Product Relationship Rules

Processing Rules

A save of an active rule does not change the product links. The links change only when the rules run: with the cron job, with the Apply Rules button, or with the Save and Apply button.

A save changes the links at once in two cases:

• A save of an inactive rule deletes the links that the rule generated. Deleting the rule does the same.
• A save that changes the link type of a rule deletes the links that the rule generated for its former link type.

Apply From the Admin

• Catalog > Product Relationship Rules > Apply Rules runs all the active rules.
• Save and Apply on the rule page saves the rule. Then it runs all the active rules of the same link type, because they compete for the same products by priority.

Both buttons put the run in the message queue, so the page does not wait. A queue worker runs it in the background, and the links change when the run is complete. The workers start from cron, so cron must run on the server. System > Tools > Message Queue shows the run, in the queue cataloglinkrule.

When the run is complete, the administrator who clicked the button gets a message in System > Notifications. The newest message also shows in the bar at the top of the next admin page that this administrator opens. If the run fails, the message has the error. When the cause is not in the data, for example a lost database connection, the queue tries the run again.

If you click a button again while a run of the same link type waits, Maho does not add a second run. If you click while a run is in progress, Maho adds one more run after it, because the run read the rules when it started.

Automatic Processing (Cron)

By default, rules are processed daily at 3:00 AM (server time) via the cron job:

cataloglinkrule_apply_all

Manual Processing (CLI)

Process all rules immediately from the command line:

# Process all active rules for all link types
./maho cron:run cataloglinkrule_apply_all

# View the cron job status
./maho cron:list

How Processing Works

1. Load Active Rules: Fetches all active rules within their date ranges, ordered by priority (lowest number first)
2. Group by Link Type: Groups rules by link type (related, up-sell, cross-sell) to process each type separately
3. Build Product-Rule Map: For each rule in priority order, finds all products matching source conditions and assigns them to the first matching rule (highest priority wins)
4. Batch Products: Splits matched products into batches of 100 for memory-efficient processing
5. Process Each Batch (within transaction):
6. Delete Old Links: Removes all existing product links for products in this batch for this link type
7. For Each Product:
   • Loads the source product with all attributes (needed for Source Match conditions)
   • Matches target products based on target conditions (sorting is applied during matching)
   • Skips the target products that the storefront cannot show (see Products That a Rule Never Links)
   • Applies max links limit if configured
   • Excludes self-links (product linking to itself)
   • Creates new link records with sequential position values
8. Commit Transaction: All changes for the batch are committed atomically (or rolled back on error)

Technical Details

Rules are stored in the catalog_product_link_rule table.

Best Practices

Rule Organization

1. Set maximum links: Use reasonable limits (4-8 typically) to prevent oversized relationship sets
2. Schedule off-peak: Run cron during low-traffic hours
3. Use specific conditions: Narrow conditions improve processing speed
4. Monitor rule count: Fewer, well-designed rules perform better than many overlapping rules