Custom Referral Eligibility Rules
Referral eligibility rules define when a referral counts and what it earns. In TinyRefs, rules are evaluated deterministically based on explicit business events sent by your application.
This page explains how rule-based referral verification works in practice and why it matters for SaaS workflows.
Example timeline
This example anchors how eligibility is reached after multiple events across billing cycles.
Day 0
A user signs up with a referral code. Your app sends an attribution event.
Billing cycle 1 and 2
Invoice events arrive. The rule is not yet satisfied, so no earning is recorded.
Billing cycle 3
The rule is satisfied. TinyRefs writes a ledger row and the referral becomes eligible.
What eligibility rules are
Eligibility rules are conditions applied to events over time. When the conditions are met, a referral becomes eligible and an earning is recorded in the ledger. Each earning appears as a line item tied to the referrer, the referred customer, and the triggering event.
Rule scope
Rules are defined per referral program and evaluated per referred customer. Each referral has its own event history and rule outcome.
Not payment-only verification
Payment events are one input, not the only input. Rules can wait for milestones, usage thresholds, or multiple billing cycles before crediting a referral.
Why payment-based verification falls short
Simple verification tied to a single payment event misses important SaaS realities. Eligibility often depends on what happens after the first charge.
Trials and delayed conversion
A referral might start as a trial. Credit should only apply after conversion or after a retention threshold.
Refunds and reversals
If a payment is refunded or reversed, a payment-only rule can over-credit. Rules based on explicit events can account for that.
Non-payment milestones
Some programs verify based on activation or usage. These milestones require business events that are not invoices.
How TinyRefs evaluates rules
Evaluation is cumulative and deterministic. Rules are checked against the event history for each referred customer. Events can arrive over days or months.
Attribution event
A user signs up with a referral code. Your app sends an attribution event that links the customer to the referrer.
Subsequent business events
Your app sends events such as subscription.created, invoice.paid, or custom milestones. Rules evaluate when eligibility is met.
Rule satisfaction over time
Rules can depend on sequences or thresholds. When conditions are satisfied, TinyRefs writes a row to the earnings ledger.
Single source of truth
Each referral has a single event history and rule outcome. Reports are derived from those ledger entries.
For the broader event model, see event-based referral tracking.
Common rule patterns
These patterns show the kind of eligibility logic teams typically need. Each relies on explicit events rather than inferred behavior.
- Subscription active for N billing cycles
- First paid invoice triggers eligibility
- Percentage of each invoice after eligibility
- One-time credit after a milestone event
When custom rules matter most
Custom rules are most useful when verification depends on business logic rather than a single payment event.
SaaS and subscriptions
Referrals often depend on retention or billing cycle thresholds, not just signup.
Long sales cycles
Eligibility can be delayed until a contract is active or usage reaches a milestone.
Usage-based or hybrid billing
Events may be usage or threshold based rather than tied to a single invoice.
For SaaS-specific examples, see SaaS referral tracking.
Rule timeline illustration
Rule-based verification, not inference
Eligibility is driven by the events you send and the rules you define. The results are recorded in the ledger and surfaced in reports and exports.
Learn more about event-based tracking in event-based referral tracking.
This is one part of the system. Join the TinyRefs waitlist to follow along as TinyRefs is built.