B2B Marketplace Commission State Machines: Deep Implementation Playbook & Code Teardown

Direct Answer: B2B Marketplace Commission State Machines

B2B marketplace commission state machines require robust finite state engines to handle multi-tiered revenue splits, enterprise credit lines, and disputed escrow funds. Implementing these systems in Ruby on Rails 8 with AASM prevents silent data corruption, ensures ACID-compliant payouts, and scales reliably through high-volume asynchronous job queues.

Architectural Overview: The B2B Commission Lifecycle

Unlike consumer marketplaces that rely on simple upfront authorization and capture models, enterprise B2B marketplaces must navigate complex workflows. These include Net-30/60 invoice cycles, milestone-based payments, tax exemptions across multiple jurisdictions, and retroactive fee adjustments caused by volume discounts or enterprise tier shifts.

To prevent race conditions and split-brain scenarios between internal ledgers and payment gateways (such as Stripe Connect Custom or Adyen for Platforms), your architecture must decouple transaction events from ledger updates. We recommend a distributed event-driven approach centered around a persistent state machine.

Core States and Transition Matrix

A production-grade commission record transitions through five distinct phases: pending_calculation, accrued, processing, settled, and disputed_or_refunded. Each state enforces strict guard conditions to ensure that money can never be disbursed twice or released while an underlying purchase order remains unpaid.

Production Implementation: Ruby on Rails 8 & AASM

Below is a production-grade state machine implementation using Ruby on Rails 8 and the aasm gem. This snippet handles atomic commission calculation, idempotency checks, and background ledger syncing.

# app/models/commission_ledger.rb
class CommissionLedger < ApplicationRecord
  include AASM

  belongs_to :order
  belongs_to :vendor
  belongs_to :buyer

  validates :amount_cents, presence: true, numericality: { greater_than_or_equal_to: 0 }
  validates :currency, presence: true

  aasm column: :workflow_state do
    state :pending_calculation, initial: true
    state :accrued
    state :processing
    state :settled
    state :disputed
    state :refunded

    event :calculate do
      transitions from: :pending_calculation, to: :accrued, guard: :valid_order_totals?
    end

    event :disburse do
      transitions from: :accrued, to: :processing, guard: :funds_cleared?
      after do
        PayoutTransferJob.perform_later(self.id)
      end
    end

    event :complete_settlement do
      transitions from: :processing, to: :settled
    end

    event :flag_dispute do
      transitions from: [:accrued, :processing], to: :disputed
      after do
        FreezeVendorPayoutsJob.perform_later(vendor_id)
      end
    end

    event :process_refund do
      transitions from: [:settled, :disputed], to: :refunded
    end
  end

  private

  def valid_order_totals?
    order.total_cents > 0 && order.line_items.any?
  end

  def funds_cleared?
    order.payment_status == 'paid' || order.credit_term_approved?
  end
end

Handling Enterprise Invoicing & Net-Term Escrows

In B2B transactions, the buyer rarely pays via instant credit card authorization. Instead, they issue purchase orders backed by Net-30, Net-60, or structured milestone schedules. Consequently, your state machine cannot assume instant liquidity.

When an order is placed via an enterprise credit line, the commission enters an accrued state. The marketplace ledger records the platform fee as an account receivable. Only when the enterprise buyer’s payment hits the escrow account—or when a verified trade credit partner (e.g., TreviPay or Stripe Capital) assumes default risk—does the state machine allow the transition to processing and eventual payout to the vendor.

2026 Commercial Pricing & Architecture Comparison

When deciding whether to build a custom B2B marketplace engine or license an off-the-shelf solution, engineering leaders must balance upfront velocity against long-term operational flexibility. The table below outlines the financial and technical trade-offs.

At TechVinta, our senior engineering teams specialize in architecting resilient B2B payment and commission pipelines. We provide dedicated development squads with guaranteed 4 to 6-hour US timezone overlap, ensuring seamless daily syncs, rapid code reviews, and high-velocity delivery.

Frequently Asked Questions

How do you handle race conditions when concurrent webhooks update a commission state?

Race conditions are mitigated by combining database-level row locking (using with_lock in ActiveRecord) with idempotency keys supplied by payment gateway webhooks. If two asynchronous jobs attempt to transition the same commission record simultaneously, the database lock serializes access, while the idempotency check discards duplicate state transition requests.

Can this state machine model accommodate dynamic vendor tier commissions?

Yes. By injecting a calculation service object into the calculate event guard, the system can query historical vendor volume over a rolling 12-month window, apply volume-based discounts or progressive fee structures, and persist the exact commission percentage applied at the moment of order creation.

What is the best way to audit ledger changes for financial compliance?

We recommend pairing your state machine with an append-only audit log table or utilizing event-sourcing patterns. Every successful state transition should emit a immutable ledger event record that captures the actor, timestamp, previous state, and resultant financial delta, ensuring complete traceability during financial audits.