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.