Rewards & Attribution

Attribution

A referral is attributed when the referred user performs the required action (reaching the reward milestone). The referral must still be in pending status and within the expiration window.

Expiration window

Set the expiration window in referral setup. The default is 30 days. If the referred user does not complete the required action within this window, the referral expires and no reward is granted.

Expiration is checked lazily: when your app looks up a referral, Tolinku checks if the expiration window has passed and updates the status if needed.

Milestone-based attribution

If you have configured custom milestones, the referral progresses through each milestone as your app reports them:

pending → signup → first_order → completed

Each milestone is recorded with a timestamp. The referral is marked as completed (and the reward is triggered) only when it reaches the reward milestone.

Your app reports milestones via the API:

POST /v1/api/referral/milestone
{
  "referral_code": "ABC1234567",
  "milestone": "first_order"
}

Rewards

Tolinku tracks reward eligibility but does not process rewards directly. You can configure rewards for both the referrer and the referred user (referee) in your referral setup.

When a referral is completed:

1. The referral status changes to completed.
2. The referrer reward type and value (from your Appspace settings) are recorded on the referral.
3. If configured, the referee reward type and value are also recorded.
4. A referral.completed webhook is fired.
5. Your app grants the rewards in your own system (credits, discounts, free months, etc.).

After granting a reward, your app can mark it as claimed:

POST /v1/api/referral/claim-reward
{
  "referral_code": "ABC1234567"
}

For the referred user’s reward:

POST /v1/api/referral/claim-referee-reward
{
  "referral_code": "ABC1234567"
}

Each endpoint updates a separate reward_claimed / referee_reward_claimed flag, so the dashboard reflects which rewards have been fulfilled for each side.

Tip

Use webhooks for real-time reward processing. When the referral.completed event fires, your server can automatically credit both the referrer’s and referee’s accounts without any manual intervention.

Ecommerce auto-completion

If your app tracks purchases via the Tolinku SDK, referrals can auto-complete when a referred user makes a purchase. This is the simplest way to implement a “reward on first purchase” referral program.

How it works

1. A referred user is linked to a referral via complete() (which sets referred_user_id and leaves the referral in pending status).
2. The referred user makes a purchase. Your app tracks it normally via ecommerce.purchase() with the user’s ID.
3. Tolinku sees the purchase event, finds a pending referral where referred_user_id matches the purchaser, and advances the referral to the configured milestone.
4. If that milestone matches the Reward Milestone, the referral auto-completes and rewards are stamped.

After the first purchase completes the referral, subsequent purchases by the same user have no effect (there is no longer a pending referral to match).

Configuration

In App Config > Referrals:

1. Check Auto-complete referral on purchase.
2. Set Milestone to trigger on purchase to the exact same value as Reward Milestone.

Caution

The “Milestone to trigger on purchase” value must exactly match the “Reward Milestone” value. If they differ (e.g. complete vs completed), the referral will never auto-complete. This is the most common configuration mistake.

Webhooks

When a referral is auto-completed via a purchase event, two webhooks fire:

• ecommerce.milestone_purchase: the ecommerce event that triggered the milestone.
• referral.completed: the standard completion webhook with reward data.

Use the referral.completed webhook to grant rewards server-side.

Preventing abuse

Tolinku includes built-in fraud checks that run automatically when a referral is completed, plus optional device-level signals you can send for stronger protection.

Automatic checks

These checks run on every referral completion with no configuration needed:

• Self-referral blocking: A user cannot refer themselves. If referred_user_id matches the referrer, the completion is rejected.
• Duplicate referred user: A user can only be referred once per Appspace. If the referred user already has a completed referral, the new one is rejected.
• Reverse referral blocking: If User A referred User B, then User B cannot refer User A. This prevents two users from farming rewards back and forth.
• One completion per referral: A referral code can only be completed once. After completion, it cannot be reused.

When a referral is rejected for abuse, the API returns 409 Conflict with the specific reason:

{ "error": "Referral flagged for abuse", "reason": "self_referral" }

Possible reasons: self_referral, already_referred, reverse_referral, same_ip, same_device.

Optional fraud signals

For stronger protection, you can send ip and device_id when creating and completing referrals. If both the referrer and referred user share the same IP address or device ID, the completion is rejected.

{
  "referral_code": "ABC123",
  "referred_user_id": "user_456",
  "ip": "203.0.113.42",
  "device_id": "device_abc123"
}

If you don’t send ip, Tolinku falls back to the server-observed IP from the request. device_id is only checked if explicitly provided by both the create and complete calls.

Tip

On mobile, use the device’s advertising ID (IDFA/GAID) or a fingerprint as the device_id. On web, a browser fingerprint or session identifier works well.

Rate limiting and caps

• Max per user: Limit how many active referrals a single user can have. This prevents users from creating hundreds of referral codes.
• Expiration window: Short expiration windows reduce the chance of stale or fraudulent referrals.
• Unique codes: Each referral gets a unique random code that cannot be guessed or enumerated.