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.

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: 2025-11-01 - To Date: 2026-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

Product Relationship Rules are processed automatically via cron job, but can also be triggered manually.

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