High-performance commission calculation engine supporting proportional and absolute commission models with tiered ranges, min/max constraints, automatic validation, binary search optimization, and ConditionalWeakTable caching. Zero allocation after initial normalization, 5M+ calculations/sec. Ideal for payment processing, affiliate marketing, broker fees.
Get Started
$ dotnet add package Pandatech.CommissionCalculatorReadme
Pandatech.CommissionCalculator
High-performance commission calculation engine for .NET 8+ supporting proportional and absolute commission models with tiered ranges, min/max constraints, and automatic validation.
Installation
dotnet add package Pandatech.CommissionCalculator
Quick Start
Define Commission Rule
using CommissionCalculator.DTO;
var rule = new CommissionRule
{
CalculationType = CalculationType.Proportional,
DecimalPlace = 4,
CommissionRangeConfigs = new List<CommissionRangeConfigs>
{
new()
{
RangeStart = 0,
RangeEnd = 500,
Type = CommissionType.FlatRate,
CommissionAmount = 25,
MinCommission = 0,
MaxCommission = 0
},
new()
{
RangeStart = 500,
RangeEnd = 1000,
Type = CommissionType.Percentage,
CommissionAmount = 0.1m,
MinCommission = 70,
MaxCommission = 90
},
new()
{
RangeStart = 1000,
RangeEnd = 10000,
Type = CommissionType.Percentage,
CommissionAmount = 0.2m,
MinCommission = 250,
MaxCommission = 1500
},
new()
{
RangeStart = 10000,
RangeEnd = 0, // 0 = infinity
Type = CommissionType.FlatRate,
CommissionAmount = 2000,
MinCommission = 0,
MaxCommission = 0
}
}
};
Calculate Commission
Standard (principal-based):
decimal principal = 1000m;
decimal commission = Commission.ComputeCommission(principal, rule);
// Result: 25 (flat) + 70 (min enforced) = 95
Selector-based (different selection and application values):
decimal orderPrice = 2000m; // Amount to calculate commission on
decimal ticketCount = 3m; // Value to select the range
// Select range based on ticketCount, apply commission to orderPrice
decimal commission = Commission.ComputeCommission(orderPrice, ticketCount, rule);
Use case: When the value that determines which range to use (e.g., ticket quantity) differs from the amount you calculate commission on (e.g., order total).
Calculation Types
Proportional (Tiered)
Commission accumulates across tiers as the amount increases:
var proportional = new CommissionRule
{
CalculationType = CalculationType.Proportional,
CommissionRangeConfigs = new List<CommissionRangeConfigs>
{
new() { RangeStart = 0, RangeEnd = 100, Type = CommissionType.Percentage, CommissionAmount = 0.05m },
new() { RangeStart = 100, RangeEnd = 0, Type = CommissionType.Percentage, CommissionAmount = 0.03m }
}
};
// For $200:
// - First $100: $100 * 5% = $5
// - Next $100: $100 * 3% = $3
// Total: $8
Absolute (Flat per tier)
Only the matching tier's commission applies:
var absolute = new CommissionRule
{
CalculationType = CalculationType.Absolute,
CommissionRangeConfigs = new List<CommissionRangeConfigs>
{
new() { RangeStart = 0, RangeEnd = 100, Type = CommissionType.FlatRate, CommissionAmount = 10 },
new() { RangeStart = 100, RangeEnd = 0, Type = CommissionType.FlatRate, CommissionAmount = 25 }
}
};
// For $200: $25 (uses second tier only)
Range Configuration
CommissionRangeConfigs Properties
| Property | Type | Description |
|---|---|---|
RangeStart | decimal | Start of range (inclusive) |
RangeEnd | decimal | End of range (exclusive), 0 = infinity |
Type | CommissionType | FlatRate or Percentage |
CommissionAmount | decimal | Commission value (flat amount or percentage like 0.1 for 10%) |
MinCommission | decimal | Minimum commission for this range |
MaxCommission | decimal | Maximum commission for this range, 0 = infinity |
CommissionType
- FlatRate: Returns
CommissionAmountdirectly (min/max ignored) - Percentage: Calculates
principal × CommissionAmount, clamped by min/max
Percentage Limits
For safety, percentage commissions are limited to ±1000%:
// ✅ Valid: 10% = 0.1
CommissionAmount = 0.1m
// ❌ Invalid: 1500% = 15 (throws exception)
CommissionAmount = 15m
Validation
Automatic Validation
Validation occurs automatically on first use:
decimal commission = Commission.ComputeCommission(1000m, rule);
// Validates rule, caches normalized version, computes result
Manual Validation
bool isValid = Commission.ValidateRule(rule);
Validation Rules
✅ Required:
- At least one range starting at 0
- Ranges must be contiguous (no gaps)
- Ranges must cover [0, ∞)
MaxCommission ≥ MinCommission(when MaxCommission ≠ 0)
❌ Forbidden:
- Overlapping ranges
- Gaps in coverage
- Equal
RangeStartandRangeEnd(except single range: both 0) - Percentage commission outside ±1000% (±10 as decimal)
DateTime Overlap Checker
Utility for validating commission period overlaps:
using CommissionCalculator.Helper;
using CommissionCalculator.DTO;
var period1 = new List<DateTimePair>
{
new(new DateTime(2024, 1, 1), new DateTime(2024, 1, 10))
};
var period2 = new List<DateTimePair>
{
new(new DateTime(2024, 1, 5), new DateTime(2024, 1, 15))
};
bool hasOverlap = DateTimeOverlapChecker.HasOverlap(period1, period2);
// Result: true
Performance
- 5+ million calculations/second (after initial validation/normalization)
- Zero allocations per calculation (after cache hit)
- Binary search for range lookup: O(log n)
- Prefix sum optimization for proportional calculations
- ConditionalWeakTable caching of normalized rules
Performance characteristics:
First calculation: ~50μs (validation + normalization + computation)
Subsequent calculations: ~200ns (cache hit + binary search + math)
Memory: ~1KB per cached rule
Advanced Usage
Single Range (Flat Commission)
var flatRule = new CommissionRule
{
CalculationType = CalculationType.Absolute,
CommissionRangeConfigs = new List<CommissionRangeConfigs>
{
new()
{
RangeStart = 0,
RangeEnd = 0, // Special case: both 0 for single range
Type = CommissionType.FlatRate,
CommissionAmount = 50,
MinCommission = 0,
MaxCommission = 0
}
}
};
// Any amount: $50 commission
Progressive Percentage with Caps
var capped = new CommissionRule
{
CalculationType = CalculationType.Proportional,
CommissionRangeConfigs = new List<CommissionRangeConfigs>
{
new()
{
RangeStart = 0,
RangeEnd = 1000,
Type = CommissionType.Percentage,
CommissionAmount = 0.05m,
MinCommission = 10, // At least $10
MaxCommission = 50 // No more than $50 per tier
},
new()
{
RangeStart = 1000,
RangeEnd = 0,
Type = CommissionType.Percentage,
CommissionAmount = 0.02m,
MinCommission = 20,
MaxCommission = 0 // Unlimited on second tier
}
}
};
Selector-Based Example
// Event ticketing: commission based on ticket count, applied to total price
var ticketRule = new CommissionRule
{
CalculationType = CalculationType.Absolute, // Required for selector-based
CommissionRangeConfigs = new List<CommissionRangeConfigs>
{
new() { RangeStart = 0, RangeEnd = 10, Type = CommissionType.Percentage, CommissionAmount = 0.1m },
new() { RangeStart = 10, RangeEnd = 0, Type = CommissionType.Percentage, CommissionAmount = 0.05m }
}
};
decimal orderTotal = 500m;
decimal ticketsSold = 15m;
// Uses second range (15 tickets), applies 5% to $500 order
decimal commission = Commission.ComputeCommission(orderTotal, ticketsSold, ticketRule);
// Result: $25
Conventions
- Infinity as 0: Set
RangeEnd = 0orMaxCommission = 0to represent ∞ - Complete coverage: Rules must cover [0, ∞) with no gaps
- Exclusive end:
RangeEndis exclusive (range is [Start, End)) - Decimal precision: Use
DecimalPlaceto control rounding (default: 4)
Common Patterns
Affiliate Marketing
// Higher commission for higher sales
CalculationType = CalculationType.Absolute
Ranges:
$0-$1000: 5%
$1000-$5000: 7%
$5000+: 10%
Payment Processing
// Tiered fees that accumulate
CalculationType = CalculationType.Proportional
Ranges:
$0-$10,000: 2.9% + $0.30 min
$10,000+: 1.5%
Broker Fees
// Fixed fee per transaction tier
CalculationType = CalculationType.Absolute
Ranges:
$0-$10,000: $9.99
$10,000-$100,000: $19.99
$100,000+: $49.99
License
MIT