Skip to content
Docs

Referral Links Overview

Referral links are the heart of BitEasy’s attribution system. They connect your partners to your app and enable accurate tracking of who referred each subscriber.

Section titled “What is a Referral Link?”

A referral link is a human-readable identifier (called a referral code) that:

  • Maps a partner to a specific app
  • Is used in the attribution flow to identify the referrer
  • Can be shared by partners with their audience

Examples of referral referral codes:

  • alice
  • summer-promo
  • podcast-50
  • launch
Section titled “How Referral Links Work”

When a partner shares their referral link:

flowchart TB
    A[User clicks partner's link] --> B["/defer or /defer-preflight called with referral code"]
    B --> C[User installs app]
    C --> D{Attribution Mode}
    D -->|Window-based| E["/claim attributes to referral code within time window"]
    D -->|Code-based| F["User enters code → /claim attributes"]
    E --> G[Partner gets credit]
    F --> G

Window-Based Attribution

Section titled “Window-Based Attribution”
  1. User clicks partner link (e.g., example.com/?referralCode=alice-yearly-2026)
  2. /defer is called with the referral code
  3. User installs the app
  4. /claim automatically matches the install to the referral within the time window
  5. Partner Alice is credited

Code-Based Attribution

Section titled “Code-Based Attribution”
  1. User clicks partner link
  2. /defer-preflight generates a claim code
  3. User installs the app
  4. User enters the claim code in your app
  5. /claim attributes after code submission
  6. Partner is credited
Section titled “Referral Link Properties”

Each referral link has:

PropertyDescription
Referral CodeThe unique identifier (e.g., alice)
PartnerWhich partner owns this link
StatusActive or Inactive
Plan HintOptional: suggests a subscription plan
Max RedemptionsOptional: limit total uses
Redemption CountHow many times claimed
Section titled “Multiple Links Per Partner”

Partners can have multiple referral links for different campaigns or offers:

  • alice-yearly-2026 — Annual subscription promo
  • alice-monthly — Monthly subscription
  • alice-podcast-25 — 25% discount from podcast mention

This design enables:

  • Campaign tracking — See which offers perform best
  • Clear attribution — Every referral traces to a specific link
  • Granular analytics — Compare performance across promotions

Active vs Inactive

Section titled “Active vs Inactive”

Links can be toggled between active and inactive:

StatusBehavior
ActiveAccepts attribution requests with this referral code
InactiveRejects requests — returns error to caller

Use inactive status to:

  • End a promotion without deleting the link
  • Pause a partner’s referrals temporarily
  • Keep historical data while stopping new attributions

Why Not Just Use Partner ID?

Section titled “Why Not Just Use Partner ID?”

You might wonder: “Why not just use the partner’s ID directly?”

Referral links provide:

  1. Human-readable referral codes — Partners can share memorable links
  2. Multiple links per partner — Track different campaigns separately
  3. Promotional flexibility — Time-limited or capped redemptions
  4. Plan hints — Guide users to specific subscription tiers

Next Steps

Section titled “Next Steps”