referral-engine

What problem does it solve?

The Referral Engine addresses the need to automatically allocate revenue across a three-generation referral tree, ensuring predictable, auditable payouts while preventing common abuse vectors.

Core Features & Use Cases

• Distributes order value to up to three generations at fixed rates: 3% to the direct referrer, 5% to the second-generation, and 17% to the third-generation, with 25% total payout. It uses precise integer arithmetic to avoid rounding and supports reversible adjustments for refunds. It also includes abuse prevention (self-referral, cycles, multi-account) and integrates with the payout ledger and batch processing.
• Use Case: A commerce platform wants to reward a chain of referrals on each order and automatically adjust payouts when refunds occur, while maintaining audit trails.

Quick Start

Initialize the engine with a test order and verify that ledger entries show 3%, 5%, and 17% allocations for the direct, second, and third generations.