Priority-Based Resolution

Handle scenarios where customers match multiple matrices using numeric priority values and merge strategies.

Overview

Customers can match multiple matrices through:

Different matching attributes (group + region + company)
Manual matrix assignments
Overlapping date ranges
Broad attribute rules (OR logic)

The Priority System resolves these conflicts predictably and transparently.

Priority Field

Every matrix has a priority field:

Type: Integer
Range: 0-999
Default: 0
Rule: Higher value = higher precedence

Example:

Matrix A: Priority 10
Matrix B: Priority 20
Winner: Matrix B

Configuration

Merge Matrix Quantities

Path: Stores > Configuration > Pricesystem > Product-Customer Matrix > Merge Matrix Qtys

Setting: pricesystem/productcustomermatrix/merge_matrix_qtys

Values:

No (Default): Select Highest Priority

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 ignored completely)

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

Yes: Merge Quantity 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.

Priority Hierarchy Recommendations

Standard Hierarchy

0-9: Base/Fallback

Priority 0: Base matrix (website default)
Priority 5: Legacy/migration pricing

10-19: Standard Pricing

Priority 10: Standard retail
Priority 12: Standard wholesale
Priority 15: Regional standard

20-29: Promotional Pricing

Priority 20: Standard promotions
Priority 22: Seasonal sales
Priority 25: Flash sales

30-39: VIP/Contract

Priority 30: VIP tier pricing
Priority 32: Annual contracts
Priority 35: Enterprise agreements

40-49: Emergency Overrides

Priority 40: Temporary fixes
Priority 45: Urgent campaigns

50+: Reserved

Priority 50+: System overrides
Priority 99: Testing
Priority 999: Absolute override (avoid)

Resolution Scenarios

Scenario 1: Same Priority

Setup:

Matrix A: Priority 10
Matrix B: Priority 10

Merge = No:

Undefined behavior! (might be ID order, creation order, or random)
Solution: Assign unique priorities (10 vs 11)

Merge = Yes:

Merges tiers from both
Best price wins at each tier
Defined behavior

Best Practice: Avoid same-priority conflicts by using unique values.

Scenario 2: Clear Winner

Setup:

Matrix A: Priority 10 (Standard wholesale)
Matrix B: Priority 30 (VIP contract)

Merge = No:

Use Matrix B only (Priority 30 > 10)

Merge = Yes:

Merge tiers from both
VIP contract prices likely win at each tier (better pricing)
But if wholesale has unique tiers, customer gets those too

Scenario 3: Three-Way Conflict

Setup:

Customer matches three matrices:
- Matrix A: Priority 15 (Wholesale)
- Matrix B: Priority 20 (California Regional)
- Matrix C: Priority 30 (ACME Contract)

Product X prices:
- A: qty=1 ($100), qty=10 ($95)
- B: qty=1 ($98), qty=25 ($92)
- C: qty=1 ($96), qty=50 ($88)

Merge = No:

Use ONLY Matrix C (Priority 30)
Customer gets: qty=1 ($96), qty=50 ($88)

Merge = Yes:

Merge all three matrices
Best price at each tier:
- qty=1: $96 (from C)
- qty=10: $95 (from A)
- qty=25: $92 (from B)
- qty=50: $88 (from C)
Customer gets: qty=1 ($96), qty=10 ($95), qty=25 ($92), qty=50 ($88)

Analysis: Merge gives best pricing across all tiers.

Scenario 4: Date-Based Priority Shift

Setup:

Standard pricing:
- Matrix: "Wholesale 2025"
- Priority: 15
- Dates: 2025-01-01 to 2025-12-31
- Product X: qty=1 ($100)

Campaign:
- Matrix: "Black Friday 2025"
- Priority: 25
- Dates: 2025-11-29 to 2025-12-02
- Product X: qty=1 ($75)

Timeline:

Nov 28:

Only Wholesale active: $100

Nov 29-30 (Black Friday):

Both active, campaign wins (Priority 25 > 15): $75

Dec 3+:

Only Wholesale active again: $100

Key Point: Temporary high-priority campaigns override standard pricing.

Scenario 5: Product Not in High-Priority Matrix

Setup:

Matrix A (Priority 10): Products X, Y, Z
Matrix B (Priority 20): Products X, Y (Z missing)

Customer views Product Z:

Merge = No:

Use Matrix B (higher priority)
Product Z not in Matrix B
Result: No matrix price (fallback to next pricesystem module)

Merge = Yes:

Check all matrices
Product Z found in Matrix A
Result: Uses Matrix A price for Product Z

Lesson: Merge mode more forgiving when high-priority matrices have incomplete product sets.

Scenario 6: Customer-Specific Date Override

Setup:

Matrix: "Annual Contract - ACME" (Priority 35)
- Matrix Dates: 2025-01-01 to 2025-12-31
- Company: ACME

Customer #123:
- Automatic assignment via company match
- Manual override dates: 2025-01-01 to 2025-06-30 (6-month trial)

Customer #456:
- Automatic assignment via company match
- No override dates (uses matrix dates)

Result:

Customer #123: Matrix active Jan 1 - Jun 30 only
Customer #456: Matrix active Jan 1 - Dec 31 (full year)

Key Point: Customer-specific dates override matrix dates, allowing per-customer scheduling within same matrix.

Scenario 7: Priority + Merge with Overlapping Tiers

Setup:

Matrix A (Priority 10):
- Product X: qty=1 ($100), qty=10 ($90), qty=50 ($80)

Matrix B (Priority 20):
- Product X: qty=1 ($95), qty=25 ($85), qty=100 ($75)

Matrix C (Priority 30):
- Product X: qty=1 ($98), qty=50 ($78)

Customer orders 40 units.

Merge = No (Highest Priority Only):

Use Matrix C only (Priority 30)
Best tier for qty=40: qty=1 ($98)
Result: $98/unit × 40 = $3,920

Merge = Yes (Best Price Wins):

Merge all tiers:
- qty=1: Best of ($100, $95, $98) = $95 (Matrix B)
- qty=10: Best of ($90, $95, $98) = $90 (Matrix A)
- qty=25: Best of ($80, $85, $98) = $80 (Matrix A)
- qty=50: Best of ($80, $75, $78) = $75 (Matrix B)
- qty=100: $75 (Matrix B)

Customer orders 40 units → Uses qty=25 tier: $80
Result: $80/unit × 40 = $3,200

Savings: $720 by using merge!

Analysis: Merge can significantly benefit customers by combining best prices from multiple matrices.

Priority Management

Setting Priorities

At Creation:

Identify purpose (standard/promo/VIP/contract)
Check existing matrices in same tier
Assign priority within tier
Document reasoning

Example:

Creating "Summer Sale 2025"
Purpose: Seasonal promotion
Tier: 20-29 (promotional)
Existing: Spring Sale (22)
Assign: 23 (next in sequence)
Document: "Summer campaign, overrides standard wholesale (15)"

Changing Priorities

Caution: Affects all customers assigned to matrix.

Process:

Understand current behavior
Test priority change in staging
Verify customer impact
Update during low-traffic period
Monitor after change
Document change reason

Bulk Priority Updates

Scenario: Increase all VIP priorities by 10.

SQL:

UPDATE pricesystem_product_customer_matrix
SET priority = priority + 10
WHERE name LIKE 'VIP%'
OR id IN (
  SELECT matrix_id FROM pricesystem_product_customer_matrix_attribute
  WHERE attribute_code = 'group' AND attribute_value = '4' -- VIP group
);

Caution: Test first! Affects all customers.

Testing Priority Logic

Test Case 1: Basic Priority

Setup:

Create Matrix A (Priority 10) with Product X = $100
Create Matrix B (Priority 20) with Product X = $90
Assign test customer to both matrices (manually)

Test Merge = No:

Expected: $90 (Matrix B wins)
Verify: Log in, check Product X price

Test Merge = Yes:

Expected: $90 (still $90, both have same tier)
Verify: Same result

Test Case 2: Merge Benefit

Setup:

Matrix A (Priority 10): Product X @ qty=1 ($100), qty=10 ($95)
Matrix B (Priority 20): Product X @ qty=1 ($98), qty=50 ($90)
Assign test customer to both

Test Merge = No:

Expected: Only qty=1 ($98), qty=50 ($90) from Matrix B
Verify: qty=10 tier NOT available

Test Merge = Yes:

Expected: qty=1 ($98), qty=10 ($95), qty=50 ($90)
Verify: qty=10 tier available (from Matrix A)

Test Case 3: Date-Based Priority Shift

Setup:

Matrix A: Standard pricing (Priority 15, permanent)
Matrix B: Campaign pricing (Priority 25, 7 days only)
Assign customer to both

Test Before Campaign:

Expected: Matrix A price
Verify: Check product price

Test During Campaign:

Expected: Matrix B price (higher priority)
Verify: Price changed

Test After Campaign:

Expected: Matrix A price again
Verify: Price reverted

Best Practices

1. Use Tiers, Not Random Values

Good:

0, 10, 20, 30, 40 (clear tiers)
10, 15, 20, 25, 30 (with gaps)

Bad:

7, 13, 21, 29, 33 (no pattern)
1, 2, 3, 4, 5 (no gaps)

2. Leave Gaps

Allows inserting priorities later without renumbering.

Example:

Current: 10, 20, 30
Need to insert between 10 and 20: Use 15
With consecutive (10, 11, 12): Must renumber everything

3. Document Hierarchy

Create internal documentation:

Priority Hierarchy - MageB2B Product-Customer Matrices

0-9: Base matrices
  0 = Website default pricing

10-19: Standard pricing
  10 = Standard retail
  12 = Standard wholesale
  15 = Regional standard

20-29: Promotional pricing
  20 = Standard promotions
  25 = Flash sales/urgent campaigns

30-39: VIP/Contract pricing
  30 = VIP tier
  35 = Enterprise contracts

40+: Emergency/testing

4. Test Merge Configuration

Before enabling merge:

Test with 2-3 matrices
Verify expected behavior
Check edge cases (missing products, same tiers)
Monitor after enabling

5. Avoid Priority 999

Reserve for absolute emergencies only. Creates maintenance issues.

6. Audit Regularly

Quarterly review:

List matrices by priority
Find duplicates (same priority)
Find gaps (orphaned tiers)
Verify hierarchy still makes sense

Troubleshooting

Wrong Price Displaying

Checklist:

✓ Which matrices does customer match?
✓ What are their priorities?
✓ Is merge enabled?
✓ Does product exist in high-priority matrix?
✓ Are dates valid for all matrices?
✓ Cache cleared?

Debug SQL:

-- Find customer's matrices
SELECT
  m.id,
  m.name,
  m.priority,
  m.is_active,
  m.from_date,
  m.to_date,
  CASE
    WHEN mc.from_date IS NOT NULL THEN mc.from_date
    ELSE m.from_date
  END AS effective_from_date,
  CASE
    WHEN mc.to_date IS NOT NULL THEN mc.to_date
    ELSE m.to_date
  END AS effective_to_date
FROM pricesystem_product_customer_matrix m
JOIN pricesystem_product_customer_matrix_customer mc ON mc.matrix_id = m.id
WHERE mc.customer_id = 123
  AND m.is_active = 1
ORDER BY m.priority DESC;

-- Check product prices in those matrices
SELECT
  m.name,
  m.priority,
  p.qty,
  p.price
FROM pricesystem_pricelist_product p
JOIN pricesystem_product_customer_matrix m ON m.id = p.pricelist_id
WHERE p.product_id = 456
  AND p.pricelist_id IN (
    SELECT matrix_id FROM pricesystem_product_customer_matrix_customer
    WHERE customer_id = 123
  )
ORDER BY m.priority DESC, p.qty ASC;

Merge Not Working

Symptoms: Customer only sees one matrix's prices, not merged.

Checks:

✓ merge_matrix_qtys = Yes in config?
✓ Config cache cleared?
✓ Customer actually assigned to multiple matrices?
✓ Matrices have different qty tiers to merge?

Test SQL:

-- Check merge config
SELECT * FROM core_config_data
WHERE path = 'pricesystem/productcustomermatrix/merge_matrix_qtys';

-- Check customer's matrices count
SELECT COUNT(*) FROM pricesystem_product_customer_matrix_customer
WHERE customer_id = 123;

Same Priority Issues

Symptom: Unpredictable pricing behavior.

Cause: Multiple matrices with same priority.

Resolution:

Find duplicates:

SELECT priority, COUNT(*) AS cnt
FROM pricesystem_product_customer_matrix
WHERE is_active = 1
GROUP BY priority
HAVING cnt > 1;

Assign unique priorities
Test again

Priority Not Respected

Symptom: Lower priority matrix wins.

Possible Causes:

High-priority matrix missing product
High-priority matrix expired (date range)
Customer-specific date override on lower-priority matrix
Cache issue

Debug:

Check product exists in all matrices
Verify date ranges (matrix + customer)
Clear cache
Test with fresh customer session

Advanced: Manual Priority Override

For specific customers, override priority system:

Method 1: Highest Priority Matrix

Create customer-specific matrix with priority 50+.

Example:

Standard matrices: 10-30
Customer exception: Priority 60
Always wins for that customer

Method 2: Date Range Stacking

Layer matrices with different date ranges but same customer.

Example:

Base: Priority 10, permanent
Q1 Special: Priority 20, Jan-Mar
Q2 Special: Priority 20, Apr-Jun
VIP Override: Priority 30, permanent

Customer gets VIP pricing except during Q1/Q2 when specials might offer better prices (if merge enabled).

Method 3: Customer-Specific Date Restriction

Use customer-specific dates to limit when high-priority matrix applies.

Example:

Matrix: VIP Pricing (Priority 30, permanent at matrix level)

Customer #123:
- Override dates: 2025-01-01 to 2025-06-30 (6-month trial)
- After Jun 30: Loses VIP pricing, falls back to lower-priority matrices

Customer #456:
- No override dates
- Gets VIP pricing permanently (or until matrix expires)

Integration with Other Pricesystem Modules

Matrix vs Pricelist Priority

Price Resolution Order:

Shopping cart price rules
Customer-specific prices
Product-Customer Matrices ← Higher in chain
Named Pricelists
Category prices
Catalog price

Key Point: Matrices evaluated BEFORE pricelists. If matrix price found, pricelist never checked.

Cross-Module Conflicts

Scenario: Customer has both matrix and pricelist pricing.

Resolution:

Matrix price found → Use it (pricelist ignored)
Matrix price NOT found → Fallback to pricelist

Recommendation: Use matrices OR pricelists, not both, to avoid confusion.

Performance Considerations

Priority Sorting

Indexed:

CREATE INDEX idx_matrix_priority ON pricesystem_product_customer_matrix(priority);

Query Optimization:

Matrices sorted by priority DESC
Highest priority evaluated first
If merge=No, stop after first match (fast)
If merge=Yes, evaluate all matching matrices (slower)

Merge Impact

Merge = No:

Fast: First matching matrix wins
Single database query per product

Merge = Yes:

Slower: All matrices must be checked
Multiple queries to find best price at each tier
Consider for VIP customers only

Creating Matrices - Step-by-step matrix creation
Matrix Pricing System - Core architecture and workflow
Multi-Attribute Matching - Attribute logic with AND/OR

Priority-Based Resolution

Overview

Priority Field

Configuration

Merge Matrix Quantities

No (Default): Select Highest Priority

Yes: Merge Quantity Tiers

Priority Hierarchy Recommendations

Standard Hierarchy

Resolution Scenarios

Scenario 1: Same Priority

Scenario 2: Clear Winner

Scenario 3: Three-Way Conflict

Scenario 4: Date-Based Priority Shift

Scenario 5: Product Not in High-Priority Matrix

Scenario 6: Customer-Specific Date Override

Scenario 7: Priority + Merge with Overlapping Tiers

Priority Management

Setting Priorities

Changing Priorities

Bulk Priority Updates

Testing Priority Logic

Test Case 1: Basic Priority

Test Case 2: Merge Benefit

Test Case 3: Date-Based Priority Shift

Best Practices

1. Use Tiers, Not Random Values

2. Leave Gaps

3. Document Hierarchy

4. Test Merge Configuration

5. Avoid Priority 999

6. Audit Regularly

Troubleshooting

Wrong Price Displaying

Merge Not Working

Same Priority Issues

Priority Not Respected

Advanced: Manual Priority Override

Method 1: Highest Priority Matrix

Method 2: Date Range Stacking

Method 3: Customer-Specific Date Restriction

Integration with Other Pricesystem Modules

Matrix vs Pricelist Priority

Cross-Module Conflicts

Performance Considerations

Priority Sorting

Merge Impact

Related Documentation