Referral Setup

Referral settings are configured in your Appspace settings under the Referrals section.

Enabling referrals

1. Go to App Config in the sidebar.

2. Scroll to the Referrals section.

3. Toggle Enable Referrals on.

4. Configure the settings below.

5. Click Save.

Configuration options

Setting	Description	Default
Expiration days	How many days a pending referral stays active before expiring.	30
Max per user	Maximum number of active referrals a single user can have at once. Leave blank for unlimited.	Unlimited
Milestone pipeline	Optional. Ordered steps a referral must progress through before reaching the reward milestone (e.g. “signed_up, verified, first_order”). Leave empty if you only need a single reward trigger.	None
Reward milestone	The milestone name that triggers referral completion. Pick from suggestions or type any custom value that matches your app’s logic.	completed
Reward type	The type of reward for the referrer. Options: None, Points, Credit, Discount, Custom.	None
Reward value	The referrer reward amount (e.g. “$5”, “10% off”, “1 month free”).	None
Referee reward type	The type of reward for the referred user. Same options as above. Leave as None for referrer-only rewards.	None
Referee reward value	The referred user’s reward amount.	None

Tip

The reward type and value are informational labels. Tolinku does not process payments or grant rewards directly. Your app uses webhooks or API polling to detect completed referrals and grant rewards in your own system.

Milestone pipeline

The milestone pipeline is optional. Most apps only need a single reward milestone (e.g. first_purchase) and can skip the pipeline entirely.

If your referral program has multiple steps, the pipeline enforces that milestones are reached in order. For example, a food delivery app might define:

1. signed_up - The referred user creates an account.
2. verified - The referred user verifies their email or phone.
3. first_order - The referred user places their first order (reward triggers here).

Your app reports each milestone via the API. Tolinku records the progression with timestamps. When the referral reaches the reward milestone, it is automatically marked as completed.

If you leave the pipeline empty, your app can call the completion endpoint or the milestone endpoint with any value. The referral completes when the reward milestone is reached, regardless of what came before.

Custom reward milestones

The reward milestone field accepts any text value. Common choices include completed, first_purchase, signed_up, subscribed, or verified, but you can type any string that matches your app’s logic. The value you enter here is compared against the milestone your app reports via the API or that is triggered by ecommerce auto-completion.

Ecommerce auto-completion

If your app tracks purchases via the Tolinku SDK, you can have referrals auto-complete when a referred user makes their first purchase. No manual API call is needed.

1. Check Auto-complete referral on purchase.

2. Set Milestone to trigger on purchase to the same value as your Reward Milestone (e.g. first_purchase).

3. Click Save.

Caution

The “Milestone to trigger on purchase” value must exactly match the “Reward Milestone” value. If they don’t match (e.g. complete vs completed), the purchase will update the milestone but the referral will never auto-complete.

When a referred user’s purchase event is tracked via ecommerce.purchase(), Tolinku looks for a pending referral linked to that user. If one is found, it advances the referral to the configured milestone. If that milestone matches the reward milestone, the referral completes automatically and the referrer’s reward is stamped.

Example configuration

For a “reward on first purchase” program:

Setting	Value
Milestone Pipeline	(empty)
Reward Milestone	first_purchase
Reward Type	Points
Reward Value	100
Auto-complete on purchase	Checked
Milestone to trigger on purchase	first_purchase
Referee Reward Type	None