Marketplace Commission System Development

Development of Marketplace Commission System

A commission system is the financial skeleton of a marketplace. Its complexity is underestimated at the start: it seems sufficient to multiply order amount by percentage. In practice, commission depends on category, sales volume, seller type, presence of promotions, applied coupons, delivery method, and dozens of other factors. A 1% calculation error with 10M/month turnover equals 100k rubles loss.

Data Structure

commission_rules (
  id, name, priority,
  seller_id (nullable — global or for specific seller),
  category_id (nullable),
  min_price, max_price,
  commission_type: percentage | fixed | tiered,
  commission_value,
  valid_from, valid_until,
  is_active
)

commission_tiers (
  rule_id,
  from_amount, to_amount,
  commission_value
)

order_commissions (
  order_id, seller_id,
  gross_amount,
  commission_amount,
  net_amount,
  rule_id (applied),
  calculated_at
)

Rule Selection Logic

Rules are applied by priority order. First matching rule wins. Selection algorithm:

1. Find all active rules where valid_from ≤ now ≤ valid_until
2. Filter by seller_id (seller-specific rules take priority over global)
3. Filter by product category_id
4. Filter by price range min_price ≤ order_total ≤ max_price
5. Apply rule with smallest priority (lower number = higher priority)

If no rule found — apply default rate from config.

Tiered Commissions

For large sellers, regressive scale is often applied:

Calculated monthly: accumulated turnover resets at month start, base rate applies. As turnover grows, rate decreases. Technically requires storing monthly_seller_turnover and recalculation with each order.

Commission with Discounts and Coupons

Marketplace may subsidize discounts. Different schemes:

• Seller pays discount fully — commission calculated from full price
• Platform subsidizes discount — commission from final sum, platform covers difference
• Shared — 50/50 or by agreement

Each option requires separate flag in order and separate line in financial reporting.

Delivery Commission

Some marketplaces take commission on delivery cost too. Others don't. Some take fixed fee per order regardless of amount. All variants must be configurable without code changes.

Calculation and Fixation

Commission is calculated at two points:

1. At order checkout — preliminary calculation, displayed to seller
2. At delivery confirmation — final fixation in order_commissions

Before final fixation, amount can change: partial return, order composition change. After fixation — immutable, any adjustments via separate commission_adjustments entry.

Reporting and Transparency

Seller sees in account:

• Commission per order with breakdown of applied rule
• Aggregated report for period: turnover, commission, net
• Forecast: at current turnover, rate will drop next month

Platform sees:

• Revenue report: platform earnings by category
• Rule effectiveness analysis: which rules drive more turnover/commission
• Seller comparison by profitability

Audit and Change History

Any commission rule change must be logged with changed_by, changed_at, and diff of old/new value. Critical for disputes with sellers — always show which rule applied at specific order time.

Technical Aspects

• All amounts stored as integers (cents) — no float for money
• Commission calculation extracted to separate CommissionCalculator service — testable, no side effects
• Rule changes don't affect already-calculated commissions — rule snapshot saved in order_commissions.rule_snapshot (JSON)
• Load tests: calculate 1000 orders per second without degradation

Development timeline: 5–7 weeks for complete system with tiered rates, reporting, and rule management interface.