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, or Stripe Billing. 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 because 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 the referral passes the AI fraud check, 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) are delivered through signed reward webhooks or configured store offer codes; money rewards (gift cards, prepaid Visa cards, charity donations, and cash, paid through Invitebase) draw from your prefunded balance on Growth and above. The referral finishes at reward_fulfilled. See Rewards and payouts.
Only validated referrals fire rewards, and only validated referrals count toward billing — on Indie the first 100 validated referrals are free, once per account lifetime, then $1 each; Growth charges $0.80 from the first referral. Linked-but-unqualified referrals cost you nothing. Read more on linked vs. validated.
The referral lifecycle
Every referral moves through a single state machine. Your qualification gates and the AI fraud check determine whether a referral validates. If a referral is reversed after validation, its billing is adjusted 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 the AI fraud check passed. Billable, and the only state that triggers rewards. | The qualification gate evaluates to satisfied within the window, and the referral has passed the AI fraud check 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 | Flagged by the AI fraud check. Not billed while flagged; if rejected after validation, billing is adjusted. You can review a flagged referral and unblock it. | The AI fraud check rejects the referral, or a reversal rejects it later 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
How the AI fraud decision works, and what you see for each 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.