How Invitebase works
The end-to-end consumer app referral platform.
Invitebase is the referral layer for consumer apps: one SDK across iOS, Android, and web to manage user referrals. This section of the docs walks through the entire referral flow, end to end. Each of the subsequent pages cover one specific part of the referral flow.
The referral flow
Each user gets a unique share link
Every user of your app receives their own unique referral link they can share with friends and family. Links are generated automatically by default, but can be customized to your domain. Users can also customize their slug directly from your app, like https://mycompany.refr.link/thomas or https://invite.mydomain.com/samantha1.
An invite link is received
When an invite link is shared with a new user, the link opens to the offer page - a web-based landing page. Offer pages are customized in the Invitebase dashboard to ensure they match your branding exactly. The click is recorded idempotently and a referral is created in the clicked state. From here the visitor is routed to your website, the App Store, or Google Play.
They install and sign up
The friend's device carries the code across the install gap — clipboard handoff and Universal Links on iOS, the Play Install Referrer and App Links on Android, a first-party cookie on web. No fingerprinting, ever. When your app tracks the new user's first events with the recovered referral_code, Invitebase binds them to the clicked referral and advances it to signed_up. This is the moment the referral is linked to a referrer. See attribution.
Events flow in
Your app calls track(event, props) — or events arrive server-side via POST /v1/events, or from connected sources like RevenueCat, Adapty, Stripe Billing, or Segment. Every event lands in the same ingestion pipeline and is evaluated against the campaign's qualification gates.
Qualification gates decide
Each campaign defines what counts as a real referral. Just becuase someone signs up, doesn't mean they qualify as a valid referral. You as the developer will decide what actions a receiver must do to pass the qualification gate: sign up for a pro account, complete onboarding, or any custom event you define. As matching events arrive the referral moves to in_progress; when the gate is satisfied — and fraud checks clear — it becomes validated. If the window closes first, it expires. See Qualification gates.
The reward is fulfilled
Validation automatically creates a reward. App grants (free access, in-app unlocks) fulfill automatically and are claimed client-side through the SDK — a signed webhook can mirror them to your server; money rewards (gift cards, PayPal, Venmo, Cash App, Wise, ACH) draw from your prefunded balance. The referral finishes at reward_fulfilled. See Rewards and payouts.
Only validated referrals fire rewards, and only validated referrals count toward billing — the first 100 per month are free, then your plan's per-referral rate. Linked-but-unqualified referrals cost you nothing. Read more on linked vs. validated.
The referral lifecycle
Every referral moves through a single state machine. The engine moves referrals forward toward validation; it never un-validates referrals (reversal is a fraud or manual action, and it reverses billing too).
| State | Meaning | Entered when |
|---|---|---|
clicked | Someone opened the referral link; no signup yet. The receiver is anonomous at this point. | The refr.link offer page records the click (idempotently — repeat clicks don't create duplicates). |
signed_up | The referred user is attributed — the referral is linked and identified. | An event arrives carrying a referral_code that matches the clicked referral, binding the new user to it. |
in_progress | The referred user has made progress toward the gates but hasn't satisfied the gate. | At least one event matches a qualification condition, but the gate isn't fully satisfied yet. |
validated | Gates satisfied and fraud checks cleared. Billable, and the only state that triggers rewards. | The qualification gate evaluates to satisfied within the window, and the referral clears the deterministic fraud controls on the same pass. |
reward_pending | A reward exists and is queued for fulfillment. | Automatically on validation, after any configured hold window. |
reward_fulfilled | The reward was delivered — app grant fulfilled automatically, entitlement applied, or payout delivered. | Terminal (success). |
reward_failed | Payout delivery failed after retries (money rewards only — for example, a payout order errored). App grants fulfill automatically and never fail. | Terminal (failure); the reward can be retried or re-approved from the dashboard. |
expired | The qualification window closed before the gates were met. Never billed. | The qualification window elapses after signup without the gate being satisfied. |
rejected | Blocked by fraud rules. Never billed; if rejected after validation, billing is adjusted. | The fraud decision rejects the referral on the pass that would have validated it, or a reversal rejects it later — possible any time before fulfillment. |
Two webhook events bracket the important transitions: referral.credited fires at signed_up, and referral.validated fires at validated. See Webhooks for the full event catalog.
Where each concept lives
Campaigns
The qualification gate and reward configuration that define a campaign, its lifecycle, and how edits take effect.
Qualification gates
The QualificationGate in depth: all/any, where filters, gte thresholds, windows, worked examples.
Linked vs. validated
The distinction that drives rewards, billing, and fraud protection.
Attribution
How installs and signups are matched to referrers on iOS, Android, and web — with no fingerprinting.
Rewards and payouts
App grants and monetary payouts, two-sided rewards, holds, and the prefunded balance.
Fraud prevention
The deterministic controls that decide whether a validated referral gets paid, and the evidence behind every decision.
Users and identity
Anonymous-first identity, identify() aliasing, and how end-users appear in the dashboard.
Environments and test mode
Test vs. live keys, full data isolation, and simulating referrals before you go live.
Browse the full surface in the API reference.