Referral Tracking API
A referral tracking API gives your application programmatic control over attribution and event ingestion. It also provides reporting. Instead of relying on a billing provider integration, your app sends the data directly.
This page is for developers and product teams evaluating whether an API-based approach fits their architecture.
What a referral tracking API needs to handle
A well-designed referral tracking API covers four areas. Understanding these helps you evaluate whether a given API matches your requirements.
Attribution
Accept attribution data when a customer signs up. Link that customer to a referrer. Store the relationship for later evaluation.
Event ingestion
Accept business events as they occur. Examples include subscriptions, invoices, and milestones. The API should handle events idempotently so retries and duplicate sends do not corrupt state.
Eligibility logic
Evaluate incoming events against rules you define. Determine when a referral qualifies for credit and how much the referrer earns.
Reporting outputs
Provide endpoints to query earnings by referrer or by customer. Provide period-based exports. Outputs are ledger-style reports. The API does not move money.
Why an API matters for referral tracking
Many referral tools require direct access to your billing provider. They pull data via webhooks from Stripe or a similar service. This works until it does not.
Custom billing stacks
If you use a provider other than Stripe, a provider-coupled tool will not work. If you handle multiple providers or custom invoicing, an API lets you send events from any source.
Subscription lifecycles
Trials and renewals generate events that matter for eligibility. Upgrades, downgrades, and pauses do too. An API accepts whatever events your business logic produces.
Delayed eligibility
Some programs require referrals to remain active for N billing cycles before the referrer earns credit. An API accepts milestone events that express this logic directly.
Multiple data sources
Revenue may come from subscriptions or one-time purchases. Usage fees and external systems add more sources. An API aggregates events from each source.
How an API-based model works in practice
In practice, your application sends explicit attribution and lifecycle events. The API evaluates those events against your rules and produces a deterministic ledger of earnings.
Attribution events
When a customer signs up with a referral code, your app sends an attribution event. This is explicit: you control when and how attribution happens.
Business events
As things happen in your system, your app sends events. Examples include subscription.created and invoice.paid along with custom milestones. These events are associated with the attributed customer for later evaluation.
Rule evaluation
You define rules that determine eligibility and earnings. When events arrive, they are evaluated deterministically. Rules can express conditions like "10% of invoices after the third billing cycle."
For more on the event model, see event-based referral tracking.
Illustrative API payloads
These examples show the shape of API calls, not complete documentation. The goal is to illustrate how data flows into the system.
{
"type": "referral.attributed",
"customer_id": "cust_8a7b",
"referrer_code": "PARTNER42",
"attributed_at": "2025-01-15T09:30:00Z"
}A new customer signed up using a referral code. The customer is now linked to the referrer.
{
"type": "subscription.billing_cycle_count",
"customer_id": "cust_8a7b",
"subscription_id": "sub_3x9k",
"cycles": 3
}The customer reached a third billing cycle. Eligibility can be derived from this explicit lifecycle signal.
Idempotency and determinism
A referral tracking API handles financial data. Two properties matter:
Idempotent event ingestion
Sending the same event twice should not double-count earnings. Events are deduplicated based on identifiers you provide, so retries and at-least-once delivery are safe.
Deterministic evaluation
Given the same set of events and rules, the ledger should produce the same totals. No hidden state, no race conditions. You can audit and replay if needed.
When a referral tracking API is a good fit
SaaS products
You have signups, trials, and subscriptions. You want to send events from your own backend rather than granting third-party access to your billing provider.
Subscription businesses
Recurring revenue means ongoing events. An API lets you send renewal and milestone events that determine eligibility over time.
Teams with existing billing logic
You already have systems that know when invoices are paid and when customers upgrade. An API lets you forward that information without restructuring your stack.
Engineering teams that value control
You prefer explicit integration over magic. You want to see exactly what data is sent and how it is evaluated.
When an API approach may not fit
You want turnkey payouts
This API model does not move money. If you need automated payouts or tax compliance with payment processing built in, an API-only tool will not cover that.
Influencer marketplaces
If you need affiliate discovery plus onboarding portals and communication tools, you need a platform rather than an API.
Marketing-only programs
If your referral program is primarily a marketing campaign with landing pages and email sequences, a marketing tool may be a better fit.
Evaluate whether this API model fits your architecture
Send events, define rules, query the ledger. Outputs are reports and exports. Payouts remain in your control. Learn about event-based tracking.
If this model fits how you build, join the TinyRefs waitlist to follow progress and get early access.