Referral Attribution via API

Referral attribution is the moment a referred customer is linked to a referrer. In TinyRefs, that link is sent by your application and recorded once.

This page explains how deterministic referral attribution works, why it matters, and how it fits into event-based referral tracking.

What referral attribution means

Referral attribution answers one question: who referred whom. In SaaS systems, that relationship should be written once, stored clearly, and used consistently as later events arrive.

Direct and auditable

Attribution is not guessed from cookies or inferred from payments. Your application sends the referrer identifier when the user signs up, and the system records it.

Stable over time

Attribution does not change unless you update it explicitly. This prevents retroactive shifts in who gets credit.

What deterministic attribution means

Deterministic attribution means the same input always leads to the same referral relationship. There is no probabilistic matching or hidden logic.

Clear source of truth

The attribution event is the source of truth. All later events reference that relationship.

Auditability

You can trace why a referral was credited by reviewing the attribution event and the later business events.

This is a core part of the event-based referral tracking model.

How attribution works via API

Attribution is sent once at signup. The referred customer is linked to a referrer identifier. Later events reference that relationship for eligibility and earnings.

Attribution event

A referral code or referrer ID is captured by your application. Your app sends an attribution event to TinyRefs.

Events reference attribution

Subsequent business events are evaluated against the stored attribution. Eligibility and earnings are derived later.

Attribution is separate from eligibility

Attribution links a referrer to a customer. Eligibility determines when that referral earns credit. This separation supports delayed or complex programs.

Attribution is immediate

The relationship is recorded at signup and does not change unless you update it explicitly.

Eligibility is evaluated later

Rules run against later events such as invoice payments or lifecycle milestones. Earnings are recorded when rules are satisfied.

For rule logic, see custom referral rules.

Common attribution patterns

Attribution can be captured in a few common ways. The pattern does not matter as long as the attribution event is explicit.

  • Signup with referral code captured at account creation
  • Invite links that map to a referrer identifier
  • Account-level attribution applied when a customer is created

Example attribution flow

This example shows a referral attribution event followed by a later lifecycle event. The attribution stays constant while eligibility is evaluated over time.

Attribution 
{
  "type": "referral.attributed",
  "customer_id": "cust_481a",
  "referrer_code": "PARTNER42",
  "attributed_at": "2025-01-15T09:30:00Z"
}
Lifecycle event 
{
  "type": "subscription.billing_cycle_count",
  "customer_id": "cust_481a",
  "subscription_id": "sub_9q2d",
  "cycles": 3
}

For a full earnings example, see percentage-based referral earnings.

When explicit attribution matters most

Deterministic attribution is most important when conversions are delayed or when billing systems are complex.

SaaS products

Attribution needs to persist across trials, upgrades, and renewals.

Subscription billing

Earnings may be calculated over multiple invoices. Attribution must remain stable.

Long conversion timelines

The referral relationship should be clear even when conversion happens months later.

Attribution as a stable input

Attribution links a referrer to a customer once. Eligibility and earnings are evaluated later from business events and rules.

For the broader context, see event-based referral tracking.

This is one part of the system. Join the TinyRefs waitlist to follow along as TinyRefs is built.