Installation & Configuration

Complete installation guide and configuration reference for Product-Customer Matrix Prices extension.

Requirements

System Requirements

Magento: 2.4.x
PHP: 8.1+
MySQL/MariaDB: 5.7+ / 10.3+
Composer: 2.x

Dependencies

Required:

mageb2b/pricesystem-core - Base pricesystem architecture
magento/framework - Magento core framework

Optional (Recommended):

mageb2b/pricesystem-pricelist - Named pricelists (for integration scenarios)
mageb2b/pricesystem-categoryprice - Category-based pricing

Installation

Step 1: Install via Composer

composer config bearer.repo.softwaresilo.io composer config repositories.softwaresilo composer https://repo.softwaresilo.io/ composer require mageb2b/pricesystem-productcustomermatrix:*

Step 2: Enable Extension

php bin/magento module:enable MageB2B_PricesystemProductCustomerMatrix

Step 3: Run Setup

php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy -f

Step 4: Clear Cache

php bin/magento cache:clean php bin/magento cache:flush

Step 5: Verify Installation

Check that tables were created:

php bin/magento db:status

Expected tables:

pricesystem_product_customer_matrix
pricesystem_product_customer_matrix_attribute
pricesystem_product_customer_matrix_customer

Admin menu should show: Catalog >Product-Customer Matrices

Configuration

Configuration Path

Admin Panel >Stores > Configuration > Pricesystem > Product-Customer Matrix

Core Settings

Enable Matrix Pricing

Path: pricesystem/productcustomermatrix/enabled

Options:

Yes (Default): Matrix pricing active
No: Matrix pricing disabled (fallback to other pricesystem modules)

Effect:

When disabled, all matrices ignored regardless of active status
Useful for testing or temporary disablement

Enable Auto-Assign Customers

Path: pricesystem/productcustomermatrix/enable_auto_assign_customers

Options:

Yes (Recommended): Automatic customer assignment based on attributes
No: Manual assignment only

How It Works:

When Enabled:

Customer logs in
System evaluates all active matrices
Matches customer attributes against matrix rules
Auto-assigns customer to matching matrices

When Disabled:

Only manual assignments work (via Customers tab in matrix edit)
Attribute fields on matrix are ignored

Use Case:

Enable: Automatic, scalable pricing
Disable: Full manual control (small customer bases)

Match Exact Type

Path: pricesystem/productcustomermatrix/match_exact_type

Options:

Loose (No - Default): Partial string matching, case-insensitive
Exact (Yes): Strict equality, case-sensitive

Examples:

Loose Matching:

Matrix Company: "ACME" Customer Company: "ACME Corporation" → MATCH (contains "ACME") Customer Company: "acme corp" → MATCH (case-insensitive)

Exact Matching:

Matrix Company: "ACME" Customer Company: "ACME Corporation" → NO MATCH (not exact) Customer Company: "ACME" → MATCH (exact) Customer Company: "acme" → NO MATCH (case-sensitive)

Recommendation:

Use Loose for flexible matching (handles typos, variations)
Use Exact for security-sensitive scenarios (tax IDs, legal entity names)

Merge Matrix Quantities

Path: pricesystem/productcustomermatrix/merge_matrix_qtys

Options:

No (Default): Use highest priority matrix only
Yes: Merge quantity tiers from all matching matrices

Detailed Explanation:

No (Highest Priority Only)

When customer matches multiple matrices, use ONLY the highest priority matrix.

Example:

Customer matches: - Matrix A (Priority 10): Product X @ qty=1 ($100), qty=10 ($95) - Matrix B (Priority 20): Product X @ qty=1 ($98), qty=50 ($90) Result: Use ONLY Matrix B (higher priority) - qty=1: $98 - qty=50: $90 (Matrix A completely ignored)

Use Case: Simple, predictable pricing. One matrix wins.

Yes (Merge Tiers)

Combine quantity tiers from ALL matching matrices, taking best price at each tier.

Example:

Customer matches: - Matrix A (Priority 10): Product X @ qty=1 ($100), qty=10 ($95) - Matrix B (Priority 20): Product X @ qty=1 ($98), qty=50 ($90) Result: MERGE tiers, best price wins: - qty=1: $98 (from Matrix B, better than A's $100) - qty=10: $95 (from Matrix A, B has no qty=10) - qty=50: $90 (from Matrix B, A has no qty=50) Customer gets: qty=1 ($98), qty=10 ($95), qty=50 ($90) Best of both matrices!

Use Case: Complex pricing scenarios, best-of-all-matrices strategy.

Enable Matrix Validation

Path: pricesystem/productcustomermatrix/enable_matrix_validation

Options:

Yes (Default): Strict validation on matrix save
No: Allow potentially conflicting configurations

Validations:

Duplicate priorities: Warn when same priority exists (same website)
Empty attributes: Require at least one matching attribute OR manual customer assignment
Date logic: Ensure from_date <= to_date
Attribute relation: Validate attributes_relation field (AND/OR)

Recommendation: Keep enabled to prevent configuration errors.

Attribute Relation Default

Path: pricesystem/productcustomermatrix/default_attributes_relation

Options:

AND (Default): All filled attributes must match
OR: Any filled attribute matches

Example:

AND Logic:

Matrix: - Customer Group: Wholesale (2) - Country: US Customer: - Group: Wholesale ✓ - Country: US ✓ Result: MATCH (both match) Customer: - Group: Wholesale ✓ - Country: DE ✗ Result: NO MATCH (country doesn't match)

OR Logic:

Matrix: - Customer Group: Wholesale (2) - Country: US Customer: - Group: Retail (1) - Country: US ✓ Result: MATCH (country matches, group doesn't matter) Customer: - Group: Wholesale ✓ - Country: DE Result: MATCH (group matches, country doesn't matter)

Use Case:

AND: Precise targeting (Wholesale + US + California)
OR: Broad targeting (Wholesale OR VIP customers)

Advanced Settings

Cache Matrix Assignments

Path: pricesystem/productcustomermatrix/cache_assignments

Options:

Yes (Default): Cache matrix-customer assignments per session
No: Re-evaluate on every request

Performance Impact:

Enabled: Faster, recommended for production
Disabled: Slower, useful for testing/debugging

Priority Hierarchy

Path: pricesystem/productcustomermatrix/priority_tiers

Document your priority hierarchy for team reference.

Recommended Hierarchy:

0-9: Base/Fallback 10-19: Standard pricing 20-29: Promotional pricing 30-39: VIP/Contract pricing 40-49: Emergency overrides 50+: System overrides

Not a system setting, but document internally.

Database Schema

Table: pricesystem_product_customer_matrix

Main matrix container.

CREATE TABLE pricesystem_product_customer_matrix ( id INT PRIMARY KEY AUTO_INCREMENT, name VARCHAR(255) NOT NULL, is_active TINYINT DEFAULT 1, priority INT DEFAULT 0, from_date DATE DEFAULT NULL, to_date DATE DEFAULT NULL, website_id INT NOT NULL, attributes_relation VARCHAR(3) DEFAULT 'AND', -- 'AND' or 'OR' created_at TIMESTAMP, updated_at TIMESTAMP, FOREIGN KEY (website_id) REFERENCES store_website(website_id), INDEX idx_priority (priority), INDEX idx_active_dates (is_active, from_date, to_date) );

Table: pricesystem_product_customer_matrix_attribute

Customer attribute matching rules.

CREATE TABLE pricesystem_product_customer_matrix_attribute ( id INT PRIMARY KEY AUTO_INCREMENT, matrix_id INT NOT NULL, attribute_code VARCHAR(50) NOT NULL, -- 'group', 'company', 'tax', 'postcode', 'region', 'country' attribute_value VARCHAR(255) NOT NULL, FOREIGN KEY (matrix_id) REFERENCES pricesystem_product_customer_matrix(id) ON DELETE CASCADE, INDEX idx_matrix_code (matrix_id, attribute_code) );

Supported Attributes:

group - Customer group ID
company - Company name
tax - Tax/VAT number
postcode - ZIP/postal code
region - State/province/region
country - Country code (ISO 2-letter)

Table: pricesystem_product_customer_matrix_customer

Manual customer assignments with optional date overrides.

CREATE TABLE pricesystem_product_customer_matrix_customer ( id INT PRIMARY KEY AUTO_INCREMENT, matrix_id INT NOT NULL, customer_id INT NOT NULL, from_date DATE DEFAULT NULL, -- Override matrix from_date to_date DATE DEFAULT NULL, -- Override matrix to_date FOREIGN KEY (matrix_id) REFERENCES pricesystem_product_customer_matrix(id) ON DELETE CASCADE, FOREIGN KEY (customer_id) REFERENCES customer_entity(entity_id) ON DELETE CASCADE, UNIQUE KEY uk_matrix_customer (matrix_id, customer_id), INDEX idx_customer (customer_id) );

Date Override Logic:

If customer-specific dates set: Use those dates
If not set: Use matrix-level dates
Allows per-customer date customization within same matrix

Product-Price Relationship

Uses shared table from pricesystem core:

-- Inherited from pricesystem_pricelist_product -- Matrix uses same structure via polymorphic relationship CREATE TABLE pricesystem_pricelist_product ( id INT PRIMARY KEY AUTO_INCREMENT, pricelist_id INT NOT NULL, -- Maps to matrix_id for matrices product_id INT NOT NULL, qty DECIMAL(10,2) DEFAULT 1.00, price DECIMAL(20,4) NOT NULL, from_date DATE DEFAULT NULL, to_date DATE DEFAULT NULL, FOREIGN KEY (product_id) REFERENCES catalog_product_entity(entity_id) ON DELETE CASCADE, INDEX idx_pricelist_product_qty (pricelist_id, product_id, qty) );

Post-Installation Checklist

After installation, verify:

✓ Tables created: Check database for 3 matrix tables
✓ Admin menu: Catalog > Product-Customer Matrices visible
✓ Configuration: All settings appear in Stores > Configuration
✓ Permissions: Admin users can access matrix grid/edit
✓ Cache cleared: Flush all caches
✓ Compilation: DI compiled without errors

Troubleshooting

Extension Not Visible in Admin

Check:

Module enabled? php bin/magento module:status
Cache cleared? php bin/magento cache:flush
Admin permissions? Check role for matrix resources

Tables Not Created

Check:

Setup run? php bin/magento setup:upgrade
Database errors? Check var/log/system.log
Permissions? Database user needs CREATE TABLE rights

Configuration Not Saving

Check:

Config cache cleared? php bin/magento cache:clean config
Database writable? Check core_config_data table
Errors in logs? Check var/log/exception.log

Next Steps

Creating Matrices - Step-by-step guide to creating your first matrix
Matrix Pricing System - Understanding core matrix architecture