Matrix Plan Setup Documentation

Complete guide to configure and implement Matrix MLM compensation plan

Last updated: February 1, 2024 • Version: 2.1.0 • Difficulty: Intermediate

Matrix Plan Overview

The Matrix MLM compensation plan (also known as Forced Matrix) restricts the width of each level to a specific number. Once a level is filled, new members spill over to downlines, creating controlled, predictable growth with automatic team building.

Key Characteristics:

• Fixed width structure (e.g., 3x7, 2x12)
• Automatic spillover to downlines
• Controlled and predictable growth
• No balancing requirements
• Ideal for beginners and part-time distributors

How Matrix Plan Works

In a Matrix plan, each distributor has a fixed number of positions in their first level. Once these positions are filled, new members are placed in the next available position in the downline organization, creating automatic team building through spillover.

3x7 Matrix Structure Example

Level 1: 3 positions
Level 2: 9 positions (3 x 3)
Level 3: 27 positions (9 x 3)
Level 4: 81 positions (27 x 3)
Level 5: 243 positions (81 x 3)
Level 6: 729 positions (243 x 3)
Level 7: 2187 positions (729 x 3)

Total Potential: 3,279 positions

Prerequisites

Before configuring the Matrix plan, ensure you have the following prerequisites in place:

1. System Requirements

MLMPortal.in software version 2.0 or higher
MySQL 5.7+ or PostgreSQL 10+ database
PHP 7.4+ with required extensions
Minimum 2GB RAM for production environment
SSL certificate for secure transactions

2. Business Configuration

Company profile and settings configured
Product catalog with point values (PV)
Payment gateway integration
User roles and permissions defined
Tax settings configured

Important: Matrix plans require careful planning of width and depth parameters as they cannot be easily changed once distributors are enrolled.

Matrix Plan Configuration

Follow these steps to configure the Matrix plan in your MLMPortal.in admin panel.

Step 1: Access Plan Settings

Login to your MLMPortal.in admin panel
Navigate to Settings → Compensation Plans
Click on Add New Plan
Select Matrix Plan from the plan types

Step 2: Basic Plan Configuration

Configure the basic settings for your Matrix plan:

// Matrix Plan Basic Configuration
{
  "plan_name": "3x7 Matrix Plan",
  "plan_type": "matrix",
  "status": "active",
  "description": "Standard 3x7 Matrix compensation plan with automatic spillover",
  "start_date": "2024-02-01",
  "currency": "INR"
}
                

Parameter	Description	Required	Default
`plan_name`	Unique name for your Matrix plan	Yes	-
`plan_type`	Must be "matrix"	Yes	-
`status`	Plan status (active/inactive)	Yes	active
`currency`	Commission currency	Yes	INR

Matrix Structure Configuration

Configure the matrix dimensions and placement rules for your plan.

Matrix Dimensions

Define the width and depth of your matrix structure:

// Matrix Structure Configuration
{
  "matrix_structure": {
    "width": 3,
    "depth": 7,
    "max_positions": 3279,
    "allow_reentry": true,
    "reentry_level": 1,
    "cycle_type": "position"
  }
}
                

Parameter	Description	Example
`width`	Number of positions per level	3 (for 3x7 matrix)
`depth`	Number of levels in matrix	7 (for 3x7 matrix)
`max_positions`	Maximum positions in matrix	3279 (for 3x7)
`allow_reentry`	Allow distributors to re-enter	true/false
`reentry_level`	Level where reentry occurs	1

Placement Rules

Configure how new members are placed in the matrix:

// Placement Rules Configuration
{
  "placement_rules": {
    "placement_method": "spillover",
    "fill_method": "left_to_right",
    "auto_placement": true,
    "allow_specific_placement": false,
    "placement_depth_limit": 7
  }
}
                

Fill Methods:

left_to_right - Fill positions from left to right
right_to_left - Fill positions from right to left
balanced - Balance across all positions
power_leg - Place in leg with most activity

Commission Settings

Configure commission rates and calculation methods for your Matrix plan.

Level-based Commission

Matrix plans typically use level-based commission structures:

// Commission Settings
{
  "commission_settings": {
    "commission_type": "level_based",
    "levels": [
      {"level": 1, "rate": 10, "type": "percentage"},
      {"level": 2, "rate": 8, "type": "percentage"},
      {"level": 3, "rate": 6, "type": "percentage"},
      {"level": 4, "rate": 5, "type": "percentage"},
      {"level": 5, "rate": 4, "type": "percentage"},
      {"level": 6, "rate": 3, "type": "percentage"},
      {"level": 7, "rate": 2, "type": "percentage"}
    ],
    "calculation_base": "personal_volume",
    "qualification_requirements": {
      "personal_volume": 100,
      "active_downlines": 3
    }
  }
}
                

Parameter	Description	Example Value
`commission_type`	Level-based or fixed	level_based
`levels`	Commission rates per level	Array of level objects
`calculation_base`	Base for commission calculation	personal_volume
`personal_volume`	Minimum PV required	100

Fast Start & Cycle Bonuses

Configure additional bonus structures for your Matrix plan:

// Bonus Configuration
{
  "bonus_settings": {
    "fast_start_bonus": {
      "enabled": true,
      "rate": 20,
      "duration_days": 30,
      "qualification": "first_3"
    },
    "cycle_bonus": {
      "enabled": true,
      "amount": 1000,
      "qualification_cycles": 1
    },
    "leadership_bonus": {
      "enabled": true,
      "levels": [10, 15, 20],
      "requirements": {
        "personal_volume": 500,
        "team_volume": 5000
      }
    }
  }
}
                

Spillover Rules & Management

Configure spillover behavior and management for your Matrix plan.

Spillover Configuration

// Spillover Rules
{
  "spillover_rules": {
    "enabled": true,
    "method": "level_fill",
    "direction": "downline",
    "max_spillover_depth": 7,
    "allow_crossline_spillover": false,
    "spillover_qualification": {
      "min_personal_volume": 50,
      "active_status": true
    }
  }
}
                

Parameter	Description	Options
`method`	Spillover placement method	level_fill, balanced, sequential
`direction`	Spillover direction	downline, upline, crossline
`max_spillover_depth`	Maximum spillover depth	1-20
`allow_crossline_spillover`	Allow cross-line spillover	true/false

Matrix Cycling Rules

Configure cycling behavior for matrix positions:

// Cycling Configuration
{
  "cycling_rules": {
    "enable_cycling": true,
    "cycle_type": "position",
    "cycle_requirement": "level_completion",
    "recycle_position": "new_matrix",
    "cycle_bonus_amount": 500,
    "max_cycles_per_month": 3
  }
}
                

Payout Settings

Configure payout methods, schedules, and thresholds for your Matrix plan.

Payout Configuration

// Payout Settings
{
  "payout_settings": {
    "payout_frequency": "weekly",
    "payout_day": "monday",
    "minimum_payout": 500,
    "maximum_payout": 50000,
    "payout_methods": ["bank_transfer", "upi", "wallet"],
    "auto_payout": true,
    "payout_approval": "auto",
    "hold_period_days": 0
  }
}
                

Parameter	Description	Options
`payout_frequency`	How often payouts are processed	daily, weekly, monthly
`minimum_payout`	Minimum amount for payout	Any numeric value
`payout_methods`	Available payout methods	bank_transfer, upi, wallet, cheque
`hold_period_days`	Days to hold commission before payout	0-30

Testing & Validation

Test your Matrix plan configuration before going live.

Test Matrix Placement

// Test Matrix Placement
POST /api/v1/matrix/placement/test
{
  "plan_id": "matrix_001",
  "sponsor_id": "user_123",
  "new_user_id": "user_456",
  "test_scenario": "full_matrix"
}

// Response
{
  "status": "success",
  "placement_position": "1.2.3",
  "placement_level": 3,
  "spillover_used": true,
  "matrix_path": ["user_123", "user_111", "user_222"]
}
                

Test Commission Calculation

// Test Commission Calculation
POST /api/v1/commission/matrix/test
{
  "plan_id": "matrix_001",
  "user_id": "user_123",
  "level_volumes": {
    "1": 500,
    "2": 1500,
    "3": 3000
  }
}

// Response
{
  "status": "success",
  "total_commission": 450,
  "level_commissions": {
    "1": 50,
    "2": 120,
    "3": 280
  }
}
                

Validation Checklist

Test matrix placement with various scenarios
Verify spillover functionality
Test level-based commission calculations
Validate cycling and reentry rules
Test payout processing
Verify matrix visualization in genealogy

Troubleshooting

Common issues and solutions for Matrix plan configuration.

Common Issues

• Spillover not working correctly
• Commission not calculating for deep levels
• Matrix positions not filling properly
• Cycling not triggering
• Genealogy tree display issues

Debug Matrix Placement

// Enable matrix debug mode
UPDATE system_settings 
SET value = 'true' 
WHERE setting_key = 'matrix_debug_mode';

// Check placement logs
SELECT * FROM matrix_placement_logs 
WHERE plan_id = ? 
ORDER BY created_at DESC LIMIT 10;
                

Common Solutions

Verify matrix width and depth settings
Check spillover rules configuration
Validate placement method settings
Ensure qualification requirements are met
Check user active status in matrix

API Integration

API endpoints for Matrix plan integration and automation.

Core API Endpoints

// Create Matrix Plan
POST /api/v1/plans/matrix
Content-Type: application/json
Authorization: Bearer {api_key}

{
  "plan_name": "3x7 Matrix",
  "width": 3,
  "depth": 7,
  "settings": { ... }
}

// Place User in Matrix
POST /api/v1/matrix/placement
{
  "plan_id": "matrix_001",
  "sponsor_id": "user_123",
  "new_user_id": "user_456"
}

// Get Matrix View
GET /api/v1/matrix/view/{user_id}?plan_id=matrix_001

// Calculate Matrix Commission
POST /api/v1/commission/matrix/calculate
{
  "user_id": "user_123",
  "plan_id": "matrix_001",
  "period": "2024-02"
}
                

Webhook Events

Matrix plan specific webhook events for real-time notifications:

// Matrix Placement Webhook
{
  "event": "matrix.placement.completed",
  "data": {
    "plan_id": "matrix_001",
    "user_id": "user_456",
    "sponsor_id": "user_123",
    "placement_position": "1.2.1",
    "placement_level": 2,
    "matrix_path": ["user_123", "user_111"]
  },
  "timestamp": "2024-02-01T10:30:00Z"
}

// Matrix Cycle Webhook
{
  "event": "matrix.cycle.completed",
  "data": {
    "plan_id": "matrix_001",
    "user_id": "user_123",
    "cycle_number": 1,
    "cycle_bonus": 1000,
    "new_matrix_started": true
  },
  "timestamp": "2024-02-01T10:30:00Z"
}
                

Need Help with Matrix Plan Setup?

Our technical support team is available to help you configure and optimize your Matrix compensation plan.

Contact Support

Documentation

Related Guides