Download PDF Manual Back to Extension
Back to Knowledge Base
Download this page as PDF

Creating Matrices

Step-by-step guide to creating product-customer pricing matrices with attribute matching and customer assignments.

Quick Start

  1. Catalog >Product-Customer Matrices → Click "Add New"
  2. Fill basic info (name, priority, dates, attributes relation)
  3. Configure customer matching attributes
  4. Save matrix
  5. Add products with prices and quantity tiers
  6. Assign customers (automatic via attributes OR manual)
  7. Activate matrix

Creating a Matrix Container

Step 1: Navigate to Grid

Admin Panel >Catalog > Product-Customer Matrices

Grid shows existing matrices with:

  • Name
  • Active status
  • Priority
  • Attributes Relation (AND/OR)
  • Date range
  • Website
  • Number of products
  • Number of assigned customers
  • Actions

Step 2: Add New Matrix

Click Add New button.

Step 3: Fill Basic Information

Name (Required)

Descriptive name for the matrix.

Examples:

  • "Wholesale US 2025"
  • "VIP Contract - ACME Corp"
  • "California Regional Pricing"
  • "Black Friday Campaign"
  • "Partner Pricing - Company A"

Best Practices:

  • Include year for time-bound pricing
  • Include customer segment/tier
  • Avoid generic names ("Test", "Matrix 1")

Is Active (Required)

Toggle matrix on/off.

  • Yes: Matrix evaluated for customer matching
  • No: Matrix ignored, even if customers match attributes

Use Case: Prepare matrices in advance, activate when ready.

Priority (Optional)

Numeric value (0-999) for conflict resolution.

  • Default: 0
  • Higher = precedence
  • Examples:
    • 10: Standard pricing
    • 20: Promotional pricing
    • 30: VIP/contract pricing
    • 40: Emergency overrides

Leave gaps (10, 20, 30) not consecutive (10, 11, 12) to allow insertions later.

From Date (Optional)

Start date for matrix validity.

  • Format: YYYY-MM-DD
  • NULL: Active immediately
  • Example: 2025-06-01 (Summer campaign start)

To Date (Optional)

End date for matrix validity.

  • Format: YYYY-MM-DD
  • NULL: No expiration
  • Must be >= From Date
  • Example: 2025-08-31 (Summer campaign end)

Website (Required)

Website scope for matrix.

  • Default: Default website
  • Multi-website: Select specific site
  • Effect: Only customers on this website match

Attributes Relation (Required)

Logic for combining multiple attributes.

  • AND (Default): ALL filled attributes must match
  • OR: ANY filled attribute matches

AND Example:

Attributes: - Customer Group: Wholesale (2) - Country: US - Region: California Customer must be: Wholesale AND US AND California

OR Example:

Attributes: - Customer Group: Wholesale (2) - Customer Group: VIP (4) Customer must be: Wholesale OR VIP

Best Practice: Use AND for precise targeting, OR for broad targeting.

Customer Matching Attributes

These fields enable automatic customer assignment. When customers match attributes, they're auto-assigned to matrix.

Important: Attributes work together based on attributes_relation field (AND/OR).

Customer Group

Match by customer group ID.

Field: Multiple select dropdown

Example:

  • Select "Wholesale" (ID 2) and "VIP" (ID 4)
  • AND mode: Customer must be in BOTH groups (impossible - customers belong to one group)
  • OR mode: Customer can be Wholesale OR VIP (correct usage)

Use Case:

  • OR mode: Multiple groups (Wholesale, VIP, Partner)
  • AND mode: Single group + other attributes

Company

Match by company name from customer account.

Field: Text input

Example: "ACME Corporation"

Matching:

  • Loose mode: "ACME" matches "ACME Corp", "acme corporation"
  • Exact mode: Must be exactly "ACME Corporation"

Use Case: B2B contract pricing for specific companies

Tax/VAT Number

Match by tax identification number.

Field: Text input

Example: "DE123456789"

Use Case:

  • EU VAT-registered businesses
  • Tax-exempt organizations
  • Verified business accounts

Notes:

  • Usually exact match (even in loose mode)
  • Format-sensitive (include dashes/spaces as stored)

Postcode

Match by billing or shipping postcode.

Field: Text input

Example: "90210"

Use Case:

  • ZIP code-based regional pricing
  • Local delivery zones

Notes:

  • Checks both billing AND shipping addresses
  • Match if EITHER address matches
  • Loose mode: "9021" matches "90210"

Region

Match by state/province/region.

Field: Text input

Example: "California"

Use Case:

  • State-specific pricing
  • Regional campaigns
  • Tax jurisdictions

Data Quality:

  • Magento stores region as text (not ID)
  • "California" vs "CA" might not match
  • Standardize or use loose matching

Country

Match by country code.

Field: Text input (2-letter ISO code)

Example: "US"

Use Case:

  • Country-specific pricing
  • Currency localization
  • Regulatory compliance

Notes:

  • Always 2-letter ISO codes (US, DE, GB, FR, etc.)
  • Exact match even in loose mode
  • Most common matching attribute

Step 4: Save Matrix

Click Save button.

Matrix container created! Now add products.

Adding Products to Matrix

Method 1: From Matrix Edit Page

  1. Edit matrix → Navigate to "Products" tab
  2. Click "Add Products"
  3. Select products from grid (checkboxes)
  4. Set prices for each product:
    • Quantity: Tier threshold (e.g., 1, 10, 50, 100)
    • Price: Price value
    • From Date: Start date (optional, overrides matrix date)
    • To Date: End date (optional, overrides matrix date)
  5. Save

Method 2: Bulk Import

Use the CSV Import/Export Add-On for bulk changes:

The Magento ImportExport entity PricesystemProductCustomerMatrix uses a structured CSV format (matrix rows + related attribute/customer rows).

Tip: Export first and use the exported CSV as your template (it matches your installed version/config).

Method 3: Product Attribute Rules

Configure automatic product selection based on attributes.

Example:

  • Category: "Summer Collection"
  • Attribute Set: "Apparel"
  • Custom Attribute: "wholesale_eligible = Yes"

Result: All products matching attributes automatically included.

Creating Quantity Tiers

Add multiple price entries for same product with different qty values.

Example: Graduated Wholesale Pricing

Matrix: "Wholesale 2025" Product: "Widget Pro"

Qty TierPriceDescription
1$100Standard price
10$95Bulk discount (5%)
50$90Volume discount (10%)
100$85Major volume (15%)

Customer orders 75 units: Gets $90/unit (Qty 50 tier applies)

How Qty Tiers Work:

  • System finds largest qty tier <= cart quantity
  • If customer orders 25 units: Uses qty=10 tier ($95)
  • If customer orders 150 units: Uses qty=100 tier ($85)

Assigning Customers to Matrix

Configure matching attributes on matrix (see above).

Example:

Matrix: "Wholesale US 2025" Attributes Relation: AND Customer Group: Wholesale (2) Country: US Region: California

Result: All wholesale customers in California, USA auto-assigned.

Configuration Required:

  • enable_auto_assign_customers = Yes

Trigger Points:

  • Customer logs in
  • Customer updates profile
  • Customer group changes
  • Admin manually triggers re-evaluation
  • Cron job (if configured)

Method 2: Manual Customer Assignment

Matrix Edit Page >Customers Tab:

  1. Click "Add Customers"
  2. Search and select customers
  3. Optional: Set customer-specific dates:
    • From Date: Override matrix from_date for this customer
    • To Date: Override matrix to_date for this customer
  4. Save

Result: Only selected customers assigned.

Use Cases:

  • Override automatic rules for specific customers
  • Exception handling (VIP gets special matrix)
  • Testing with test customers

Customer-Specific Date Example:

Matrix Dates: 2025-01-01 to 2025-12-31 Customer #123 Override: 2025-01-01 to 2025-06-30 (6-month contract) Customer #456 Override: NULL (uses matrix dates)

Common Workflows

Workflow 1: Wholesale Pricing

Goal: Create wholesale pricing for US customers in 2025.

  1. Create matrix:

    • Name: "Wholesale US 2025"
    • Active: Yes
    • Priority: 15
    • Attributes Relation: AND
    • From Date: 2025-01-01
    • To Date: 2025-12-31
    • Customer Group: Wholesale (2)
    • Country: US

  2. Add products:

    • Import CSV with all products
    • Or add manually via Products tab
    • Set quantity tiers: qty=1, qty=10, qty=50, qty=100

  3. Test:

    • Log in as wholesale customer in US
    • Verify prices display
    • Test quantity tier changes in cart

Workflow 2: Seasonal Campaign

Goal: Black Friday sale (Nov 29 - Dec 2, 2025) for all customers.

  1. Create matrix:

    • Name: "Black Friday 2025"
    • Active: Yes
    • Priority: 25 (higher than standard pricing)
    • From Date: 2025-11-29
    • To Date: 2025-12-02
    • Customer Group: General (1) - all customers
    • No other attributes (all customers match)

  2. Add products:

    • Select sale products
    • Set discounted prices (single qty=1 tier)

  3. Automatic:

    • Activates Nov 29
    • Deactivates Dec 3
    • No manual intervention

Workflow 3: Multi-Company B2B Pricing

Goal: 3 partner companies with different pricing.

  1. Create matrices:

    • Matrix A: "Partner - ACME Corp" (Company = "ACME", Priority 30)
    • Matrix B: "Partner - XYZ Inc" (Company = "XYZ", Priority 30)
    • Matrix C: "Partner - Global LLC" (Company = "Global", Priority 30)

  2. Add products:

    • Same products across all matrices
    • Different prices per matrix (negotiated rates)

  3. Result:

    • ACME employees see ACME pricing
    • XYZ employees see XYZ pricing
    • Global employees see Global pricing

Workflow 4: Regional + Group Targeting

Goal: California wholesale customers get special pricing on California-specific products.

  1. Create matrix:

    • Name: "CA Wholesale 2025"
    • Active: Yes
    • Priority: 20
    • Attributes Relation: AND
    • Customer Group: Wholesale (2)
    • Country: US
    • Region: "California"

  2. Add products:

    • Select California-themed products only
    • Set wholesale prices with qty tiers

  3. Result:

    • California wholesale: See special prices
    • California retail: Don't see (not wholesale)
    • Texas wholesale: Don't see (not California)

Workflow 5: VIP + Extra Savings

Goal: VIP customers get 15% off everything, plus 25% off selected products.

  1. Create matrices:

    • Matrix 1: "VIP Base Pricing" (Priority 30, all products, 15% discount)
    • Matrix 2: "VIP Extra Savings" (Priority 32, selected products, 25% discount)
    • Both: Customer Group = VIP (4)

  2. Configuration:

    • merge_matrix_qtys = Yes (best price wins)

  3. Result:

    • VIP customers get 15% off all products (Matrix 1)
    • VIP customers get 25% off selected products (Matrix 2 wins for those products)

Workflow 6: Contract with Customer Override

Goal: Annual contract with ACME Corp, but Customer #12345 has 6-month trial.

  1. Create matrix:

    • Name: "Contract - ACME Corp 2025"
    • Active: Yes
    • Priority: 35
    • From Date: 2025-01-01
    • To Date: 2025-12-31
    • Company: "ACME"

  2. Add products:

    • Contract products with negotiated prices

  3. Assign customers:

    • Automatic: All ACME employees via company match
    • Manual: Customer #12345 with override dates: 2025-01-01 to 2025-06-30

  4. Result:

    • Most ACME employees: 2025-01-01 to 2025-12-31
    • Customer #12345: 2025-01-01 to 2025-06-30 (6-month trial)

Multi-Attribute Matching Examples

Example 1: AND Logic (Precise Targeting)

Matrix Configuration:

Attributes Relation: AND Customer Group: Wholesale (2) Country: US Region: California

Customer Matching:

Customer A: - Group: Wholesale ✓ - Country: US ✓ - Region: California ✓ → MATCH (all three attributes match) Customer B: - Group: Wholesale ✓ - Country: US ✓ - Region: Texas ✗ → NO MATCH (region doesn't match) Customer C: - Group: Retail ✗ - Country: US ✓ - Region: California ✓ → NO MATCH (group doesn't match)

Example 2: OR Logic (Broad Targeting)

Matrix Configuration:

Attributes Relation: OR Customer Group: Wholesale (2), VIP (4)

Customer Matching:

Customer A: - Group: Wholesale ✓ → MATCH (one attribute matches) Customer B: - Group: VIP ✓ → MATCH (one attribute matches) Customer C: - Group: Retail ✗ → NO MATCH (no attributes match)

Example 3: Complex Scenario

Goal: Wholesale customers in California OR VIP customers anywhere.

Solution: Create TWO matrices:

Matrix 1: "CA Wholesale" (Priority 20) - Attributes Relation: AND - Group: Wholesale - Country: US - Region: California Matrix 2: "VIP All Regions" (Priority 30) - Attributes Relation: AND - Group: VIP - (no location attributes)

Result:

  • California wholesale customers: Matrix 1
  • VIP customers (any location): Matrix 2
  • VIP customers in California: Matrix 2 wins (higher priority)

Testing Matrix Assignment

Test Plan

  1. Create test matrix:

    • Name: "Test - Wholesale US"
    • Customer Group: Wholesale (2)
    • Country: US
    • Active: Yes

  2. Create test customer:

    • Group: Wholesale
    • Country: US
    • Company: "Test Co"

  3. Test assignment:

    • Log in as test customer
    • Check assigned matrices (admin: Customer Edit >Matrices tab)
    • Verify matrix appears

  4. Test exclusion:

    • Change customer country to DE
    • Log out, log back in
    • Verify matrix NOT assigned

  5. Test re-assignment:

    • Change customer back to US
    • Log out, log back in
    • Verify matrix re-assigned

Priority System in Action

Scenario: Customer Matches Multiple Matrices

Setup:

  • Customer: John Doe (Wholesale group, California, ACME Corp)
  • Matrix A: "Wholesale 2025" (Priority 15) - Matches group
  • Matrix B: "California Special" (Priority 20) - Matches region
  • Matrix C: "ACME Contract" (Priority 30) - Matches company

Configuration 1: merge_matrix_qtys = No

  • Result: Only Matrix C applies (highest priority)
  • Product X: Uses Matrix C prices only

Configuration 2: merge_matrix_qtys = Yes

  • Result: Merge qty tiers from all three
    • Matrix A: qty=1 ($100), qty=10 ($95)
    • Matrix B: qty=25 ($92)
    • Matrix C: qty=50 ($88)
    • Customer gets: qty=1 ($100), qty=10 ($95), qty=25 ($92), qty=50 ($88)
    • Best price from each matrix at each tier!

Troubleshooting

Matrix Not Showing for Customer

Checklist:

  1. ✓ Is Active = Yes?
  2. ✓ Date range valid? (from_date <= today <= to_date)
  3. ✓ Website matches?
  4. ✓ Customer matches attributes (check attributes_relation: AND/OR)?
  5. ✓ Auto-assignment enabled? (enable_auto_assign_customers = Yes)
  6. ✓ Customer logged in recently? (triggers evaluation)
  7. ✓ Cache cleared?

Debug SQL:

-- Check customer attributes SELECT entity_id, group_id, email, company FROM customer_entity WHERE entity_id = 123; -- Check matrix matching attributes SELECT m.id, m.name, m.priority, m.attributes_relation, ma.attribute_code, ma.attribute_value FROM pricesystem_product_customer_matrix m LEFT JOIN pricesystem_product_customer_matrix_attribute ma ON ma.matrix_id = m.id WHERE m.is_active = 1 ORDER BY m.priority DESC; -- Check assignments SELECT * FROM pricesystem_product_customer_matrix_customer WHERE customer_id = 123;

Wrong Prices Displaying

Checklist:

  1. ✓ Multiple matrices match? (check priority)
  2. ✓ Merge config? (merge_matrix_qtys setting)
  3. ✓ Product exists in matrix?
  4. ✓ Quantity tier matches cart quantity?
  5. ✓ Date ranges valid? (matrix + customer-specific)
  6. ✓ Other pricesystem modules active? (check price resolution order)

Attributes Not Matching

Common Issues:

  1. AND vs OR: Check attributes_relation field
  2. Data quality: Company name mismatch ("ACME" vs "ACME Corp")
  3. Match mode: Loose vs Exact (check match_exact_type config)
  4. Empty attributes: Ensure at least one attribute filled

Best Practices

Naming Conventions

  • Include year: "Wholesale 2025"
  • Include segment: "VIP Contract - ACME"
  • Include region: "California Regional"
  • Avoid generics: "Test", "Matrix 1"

Priority Management

  • Use tiers: 0, 10, 20, 30 (not 1, 2, 3, 4)
  • Leave gaps: Insert later without renumbering
  • Document hierarchy: Team reference

Attribute Selection

  • Start simple: Group + Country
  • Add complexity: Region, Company
  • Test thoroughly: Edge cases
  • Document logic: Why these attributes?

Performance

  • Don't over-create: 100s OK, 1000s might slow
  • Use specific attributes: Group faster than Company matching
  • Cache enabled: Production setting
  • Monitor: Regular audits

Next Steps

Installation & ConfigurationMatrix Pricing System

Found an issue with this documentation? Let us know