Qualification gates
The qualification gate is where you define what criteria need to be hit for a referral to be validated.
The qualification gate is where you define what counts as a referral. Instead of paying out referrals on instal, you gate validation on real behavior: a paid conversion, a completed onboarding, a usage threshold. You set this up in the dashboard, no code required, and the engine evaluates it against the referred user's ingested events.
Two ways to define your criteria
You build the gate in the Campaign Builder — no code required. Customize the criteria straight from the dashboard, choosing how a referral becomes valid one of two ways.
AI Qualification
Let Invitebase decide what a genuine, reward-worthy referral looks like. When you create a campaign it suggests criteria based on apps like yours, and its verification tools learn from your event stream to tell a real referral from a manufactured one. The more user actions you send, the faster and more accurately it predicts a valid referral. This is the recommended path — see AI verification.
Manual Qualification
Define the criteria yourself. In the gate builder you pick the events that must happen, filter them by property, set thresholds, and choose how long the referred user has to qualify. You stay in full control of exactly what validates a referral.
What a gate can check
However you build it, a gate is a set of conditions the referred user must meet, combined with all (every condition) or any (at least one), inside an optional qualification window.
| Part of the gate | What it does |
|---|---|
| Event | The action that must occur, e.g. subscription_started or workout_completed. Event pickers are populated from events Invitebase has actually seen from your app, so you select real names rather than guessing. |
| Property filter | Narrows an event to specific properties — count only subscription_started where plan is paid, not a free trial. |
| Threshold | Requires the action to happen enough times, or reach a summed value — three workouts, or purchases totaling $50. Each event contributes its value or count property, defaulting to 1 per occurrence. |
| All / any | Whether every condition must be satisfied, or just one. |
| Qualification window | How many days the referred user has after signup to satisfy the gate. Leave it open for no deadline. |
You can also work in points instead of boolean gates: assign a score to each tracked action — add a profile picture = 2, complete a workout = 8 — and validate when the referred user's total crosses a threshold. Either style is configured in the same builder.
Eligibility comes first
The Qualification Gate decide when a referral validates; a campaign's eligibility settings decide whether the referred user can qualify at all. They're checked before the gate ever starts counting, along three axes configured in the Campaign Builder:
- New users only, or returning users too — the default posture is that only genuinely new accounts qualify.
- An account-age limit — if the person created their account before the code was applied, how old that account can be and still count as "new."
- Prior payment history — whether someone who once held a paid subscription can qualify, or the reward is reserved for users who have never paid.
Referrals that fail eligibility are rejected before validation, so they never cost you anything and never inflate a referrer's counts — and since they never reach the gates, none of the evaluation below applies to them. Self-referrals are a separate check with its own signals; see Fraud prevention. For guidance on choosing these settings, see Choose your rewards.
How evaluation works
Invitebase uses events to gain an understanding of user behavior in your app. Select events are automatically tracked - download, account created, screen time - and give basic information on users. You can add additional events to help Invitebase's AI better understand user patterns and determine which referrals are genuine.
Events reach the engine from every source — SDK track() calls, server-side POST /v1/events, and connected integrations (RevenueCat, Adapty, Stripe Billing, Segment). Calling Invitebase.track("profilePictureAdded") helps Invitebase's AI predict genuineness and ensure you only pay for real referrals.
We recommend adding 6-8 events for your the most impactful user actions. Purchases, account setup, or major actions that would indicate a genuine user.
The outcome drives the state machine:
- Gate satisfied → the referral moves to
validated(after fraud checks). - Some progress (≥ 1 matching event) but not satisfied →
in_progress. - Window elapsed without satisfying →
expired. Expired referrals are never billed.
Evaluation runs on every relevant ingested event, so referrals advance in near real time, and per-condition progress is visible on the referral object (gate_progress) and in the dashboard.
Worked examples
Each of these is a few clicks in the gate builder — no config to hand-write.
| Gate | Validates when the referred user… | Window |
|---|---|---|
| Simple signup | Shows up once. Good for low-value rewards and top-of-funnel campaigns. | 7 days |
| Paid conversion | Starts a paid subscription. With RevenueCat, Adapty, or Stripe Billing connected this validates on real purchase events with zero extra instrumentation — see Reward a paid subscription. | 14 days |
| Usage threshold | Completes three workouts — three separate events, or fewer events whose value/count sum to 3. | 10 days |
Email + onboarding (all) | Verifies their email and finishes onboarding. | 7 days |
Trial or annual (any) | Converts a trial or buys an annual plan. | 30 days |
Feeding the gates
The gate builder's event pickers draw from events Invitebase has already seen from your app, plus any connected integrations (RevenueCat, Adapty, Stripe Billing, Segment) — so for common cases like a paid conversion there's nothing to instrument at all. When you want to gate on something specific to your product, that action needs to be tracked once; Custom event gates and the Events API cover the instrumentation. Whatever your app sends becomes selectable in the builder.
Before you ship a gate, the builder's live tester evaluates your draft against a sample user's event history so you can confirm it behaves as intended.
See Campaigns for how edits take effect, and Linked vs. validated for why gates are the billing boundary.