Priority System

The priority system controls the order in which payment profiles are evaluated. When multiple profiles could match a customer or cart, the profile with the lowest priority number wins.

Screenshot placeholder: payment profile grid with visible priority ordering File: ./_screenshots/priority-system.png

How Priority Works

Priority Range

Valid Range: 1-999
Lower Number: Higher priority (evaluated first)
Higher Number: Lower priority (evaluated last)

Evaluation Order

Priority 10  ← Evaluated first
Priority 50
Priority 100
Priority 500
Priority 999 ← Evaluated last

The first profile that matches stops the evaluation. Subsequent profiles are ignored.

Priority Examples

Example 1: B2B Store

Priority 10: VIP Customers
  - Group: VIP
  - Methods: All + Net 30
  - Condition: None

Priority 50: Wholesale Orders
  - Group: Wholesale
  - Methods: Bank Transfer, Invoice
  - Condition: Subtotal >= 500

Priority 100: Retail Customers
  - Group: General
  - Methods: Credit Card, PayPal
  - Condition: None

Priority 999: Default Fallback
  - Group: All
  - Methods: Credit Card
  - Condition: None

Scenario 1: VIP customer, cart €600

Check Priority 10 → MATCH (VIP group)
Result: All methods + Net 30
Priorities 50, 100, 999 are not evaluated

Scenario 2: Wholesale customer, cart €600

Check Priority 10 → No match (not VIP)
Check Priority 50 → MATCH (Wholesale, >€500)
Result: Bank Transfer, Invoice

Scenario 3: Retail customer, cart €100

Check Priority 10 → No match
Check Priority 50 → No match
Check Priority 100 → MATCH (General group)
Result: Credit Card, PayPal

Example 2: Regional Restrictions

Priority 10: EU High Value
  - Condition: Subtotal >= 1000, Country: DE/AT/CH
  - Methods: Bank Transfer only

Priority 20: EU Standard
  - Condition: Country: DE/AT/CH
  - Methods: SEPA, Credit Card

Priority 30: US High Value
  - Condition: Subtotal >= 1000, Country: US
  - Methods: ACH only

Priority 40: US Standard
  - Condition: Country: US
  - Methods: ACH, Credit Card, PayPal

Scenario: German customer, cart €1200

Check Priority 10 → MATCH (>€1000, DE)
Result: Bank Transfer only (secure payment for high value)

Scenario: German customer, cart €500

Check Priority 10 → No match (<€1000)
Check Priority 20 → MATCH (DE)
Result: SEPA, Credit Card

Priority Best Practices

1. Specific Before General

Place more specific profiles at higher priority (lower numbers):

✓ GOOD:
Priority 10: VIP + High Value (specific)
Priority 50: VIP (less specific)
Priority 100: All Customers (general)

✗ BAD:
Priority 10: All Customers (general)
Priority 50: VIP (specific) ← Never evaluated!

2. Use Gaps

Leave gaps between priorities for future insertions:

✓ GOOD:
Priority 10, 20, 30, 40, 50
(Can insert 15, 25, 35 later)

✗ BAD:
Priority 1, 2, 3, 4, 5
(No room for insertions)

3. Document Priority Logic

Add comments in profile names:

Priority 10: [P10] VIP - All Methods
Priority 50: [P50] Wholesale - Invoice Only
Priority 100: [P100] Retail - Standard Methods

4. Test Priority Order

Always test with different customer types to ensure correct priority evaluation.

Priority Conflicts

Problem: Overlapping Profiles

Priority 50: Wholesale - Invoice
  - Group: Wholesale
  - Methods: Invoice

Priority 50: High Value - Bank Transfer
  - Condition: Subtotal >= 1000
  - Methods: Bank Transfer

Issue: Both have priority 50. Evaluation order is unpredictable.

Solution: Use different priorities:

Priority 40: High Value - Bank Transfer
Priority 50: Wholesale - Invoice

Problem: Too Many Profiles

Priority 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20...

Issue: Hard to maintain and understand.

Solution: Use larger gaps:

Priority 10, 50, 100, 150, 200...

Priority Strategies

Strategy 1: Tiered Approach

Priority 1-99:   Exception rules (VIP, special cases)
Priority 100-499: Standard rules (customer groups)
Priority 500-899: Fallback rules (general restrictions)
Priority 900-999: Default rules (catch-all)

Strategy 2: Category-Based

Priority 10-19:  Customer-specific rules
Priority 20-29:  Group-specific rules
Priority 30-39:  Cart-based rules
Priority 40-49:  Product-based rules
Priority 50-59:  Region-based rules
Priority 900+:   Default fallback

Strategy 3: Simple Linear

Priority 10:  Most specific
Priority 20:  Very specific
Priority 30:  Specific
Priority 40:  Moderate
Priority 50:  General
Priority 999: Default

Debugging Priority Issues

Common Issues

Issue: Wrong profile is matching

Check: Priority order - lower number wins
Solution: Adjust priorities

Issue: Profile never matches

Check: Higher priority profile is matching first
Solution: Lower the priority number or adjust conditions

Issue: Unpredictable behavior

Check: Multiple profiles with same priority
Solution: Use unique priorities

Advanced Priority Scenarios

Scenario: Temporary Override

Priority 1: Black Friday Special
  - Condition: Date range 24-27 Nov
  - Methods: All methods + Special financing
  - Status: Active only during promotion

Priority 10: Normal VIP
  - Group: VIP
  - Methods: All methods

During Black Friday, Priority 1 matches first. After, it's disabled and Priority 10 takes over.

Scenario: A/B Testing

Priority 10: Test Group A
  - Customer IDs: 1-1000
  - Methods: New payment method

Priority 20: Test Group B
  - Customer IDs: 1001-2000
  - Methods: Standard methods

Priority 999: Control Group
  - All others
  - Methods: Standard methods

Test new payment methods with specific customer segments.