Deep Linking for Referral Programs

Referral programs rely on deep links to connect a referred user back to the person who invited them, even when the referred user has to install the app first.

The flow

1. An existing user generates a referral link (e.g. https://myapp.tolinku.com/ref/ABC123).
2. They share it with a friend via text, social media, or email.
3. The friend taps the link.
4. If the app is installed: The app opens and the referral code is captured.
5. If the app is not installed: The user sees a landing page, installs the app, and deferred deep linking passes the referral code on first open.
6. The app calls complete() to link the referred user to the referral (status stays pending).
7. The friend completes the required action (e.g. makes a purchase). If ecommerce auto-completion is enabled, the referral completes automatically.
8. The referrer receives their reward.

Setting up a referral program

1. Enable referrals

In Appspace Settings > Referrals, configure:

• Reward type: Discount, credit, or custom.
• Reward value: The amount or description.
• Completion milestone: The action that counts as a completed referral (e.g. signed_up, first_purchase).

2. Create referral links via the API

Use the Referrals API to generate unique codes:

const res = await fetch('https://myapp.tolinku.com/v1/api/referral/create', {
  method: 'POST',
  headers: {
    'X-API-Key': 'tolk_pub_your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    user_id: 'user_123',
    user_name: 'Jane Doe'
  })
});

const { referral_code, referral_url } = await res.json();
// referral_url = "https://myapp.tolinku.com/ref/ABC123"

Or use the SDK:

let result = try await Tolinku.shared!.referrals.create(
    userId: "user_123",
    userName: "Jane Doe"
)
// result.referral_url

3. Handle the referral on install

After the referred user installs and opens the app, claim the deferred deep link:

// iOS
if let link = try await Tolinku.shared?.deferred.claimBySignals(
    appspaceId: "your_appspace_id"
) {
    if let referralCode = link.referral_code {
        // Referral attributed automatically
        showReferralWelcome(referrer: link.referrer_id)
    }
}

Tolinku’s deferred deep link response includes referral_code and referrer_id when the claimed path is a referral link.

4. Link the referred user

After the referred user signs up, call complete() to link them to the referral. This sets referred_user_id on the referral but does not complete it yet (unless the reward milestone is completed, the default).

await fetch('https://myapp.tolinku.com/v1/api/referral/complete', {
  method: 'POST',
  headers: {
    'X-API-Key': 'tolk_pub_your_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    referral_code: 'ABC123',
    referred_user_id: 'user_456'
  })
});

5. Trigger completion

There are two ways the referral can complete:

Option A: Ecommerce auto-completion (recommended for purchase-based rewards)

If you have enabled “Auto-complete referral on purchase” in your settings, just track the purchase normally via the SDK. The server handles everything:

// Track the purchase as usual. The server finds the pending referral
// for this user and auto-completes it.
await tolinku.ecommerce.purchase({
  transaction_id: 'order_789',
  revenue: 49.99,
  currency: 'USD',
  items: [{ item_id: 'sku_1', item_name: 'Sneakers', price: 49.99, quantity: 1 }]
});

Caution

The “Milestone to trigger on purchase” value in your settings must exactly match the “Reward Milestone” value. If they differ (e.g. complete vs completed), auto-completion will not work.

Option B: Manual milestone update

Call the milestone endpoint directly:

await fetch('/v1/api/referral/milestone', {
  method: 'POST',
  headers: { 'X-API-Key': key, 'Content-Type': 'application/json' },
  body: JSON.stringify({ referral_code: 'ABC123', milestone: 'first_purchase' })
});

If the milestone matches the reward milestone, the referral completes and the reward is stamped.

6. Grant the reward

Listen for the referral.completed webhook, or poll the referral status. When the referral is completed, grant the reward in your system and mark it as claimed:

await fetch('/v1/api/referral/claim-reward', {
  method: 'POST',
  headers: { 'X-API-Key': key, 'Content-Type': 'application/json' },
  body: JSON.stringify({ referral_code: 'ABC123' })
});

7. Design a referral landing page

Create a landing page for the /ref route that shows:

• Who invited them (referrer name)
• What reward they will get
• Download buttons

Use the Referral template category in the visual builder.

Tracking and analytics

• View referral performance in the Referrals dashboard: total referrals, conversion rate, leaderboard.
• Use webhooks (referral.created, referral.completed) to trigger reward fulfillment in your backend.
• The leaderboard API lets you build a public leaderboard in your app.

Best practices

• Make sharing easy. Pre-populate the share message with the referral link and a compelling message.
• Show progress. Let referrers see their pending and completed referrals in the app.
• Reward both sides. Programs that reward both the referrer and the referred user see higher conversion.
• Set a billing cap. If a referral campaign goes viral, a billing cap prevents unexpected cost overruns.