Creating Referral Links

This guide walks through creating and configuring referral links for your partners.

---

Creating a New Link

1. Navigate to your app
2. Click Referral Links in the app navigation
3. Click the + New Link button
4. Fill in the link details
5. Click Create

---

Link Configuration

Referral Code

The unique identifier for this link. Requirements:

• Lowercase letters, numbers, and hyphens
• No spaces or special characters
• Must be unique within the app

Good examples:

• alice
• podcast-promo
• summer-2026

Tip

Choose referral codes that are memorable and easy for partners to share.

Partner

Select which partner this link belongs to. The partner must already exist in your Partners list.

Note

Need to create a partner first? See Managing Partners.

Plan Hint (Optional)

Suggest a specific subscription plan when this link is used:

Value	Use Case
Any (default)	No plan suggestion
monthly	Suggest monthly subscription
yearly	Suggest annual subscription

Plan hints are passed through to your app via the /claim response.

Max Redemptions (Optional)

Limit how many times this link can be redeemed:

Setting	Behavior
∞ (default)	Unlimited redemptions
Number (e.g., 100)	Link stops working after 100 claims

Use this for:

• Limited-time promotions
• Exclusive partner deals
• Controlled rollouts

Expiry (Optional)

Set an expiration date for the referral link:

Setting	Behavior
None (default)	Link never expires
Date	Link stops accepting attributions after this date

Expired links will reject /defer and /claim requests. Use this for:

• Seasonal campaigns
• Time-limited promotions
• Event-based offers

Tip

Combine expiry with max redemptions for maximum control — e.g., “First 100 users before Dec 31st.”

Payout Rate

Set the partner’s revenue share for this link:

• Enter as a percentage (e.g., 10% means the partner earns 10% of each purchase)
• Applied to all purchases attributed to this link
• Determines how much the partner earns per transaction

Payout Duration (Optional)

How long attributions remain eligible for payouts:

Setting	Behavior
None (default)	Lifetime attribution — partner earns on all future purchases
Number (e.g., 365)	Partner earns only on purchases within this many days of attribution

---

Payout Terms & Partner Agreement

Terms Are Locked After Creation

Financial terms cannot be changed after a referral link is created. If you need different terms, create a new link.

When you create a referral link, the following payout terms are locked:

• Payout Rate — Partner’s revenue share (as a percentage)
• Payout Duration — How long attributions earn payouts
• Expiry Date — When the link stops working
• Plan Hint — Suggested subscription type
• Max Redemptions — Usage limit

Why Terms Are Locked

When you create a link, the partner receives an approval email containing these exact terms. Locking the terms ensures:

• Partners know exactly what they’re agreeing to
• Terms cannot be changed unilaterally after sharing
• Full audit trail of what was agreed

Changing Terms

To change payout terms for a partner:

1. Delete the existing referral link
2. Create a new link with the updated terms
3. Partner will receive a new approval email

---

Partner Approval Flow

Before a referral link can attribute installations, the partner must approve it.

How It Works

flowchart TB
    A[You create referral link] --> B[Partner receives approval email]
    B --> C[Partner reviews terms]
    C --> D[Partner accepts terms]
    D --> E[Link becomes active]
    E --> F[Attributions can occur]

1. Link Created — You create the referral link with payout terms
2. Email Sent — Partner receives an email with the link terms
3. Partner Reviews — Partner sees the payout rate, duration, and other terms
4. Partner Accepts — Partner agrees to the terms
5. Link Active — Link can now attribute installations and earn payouts

Approval Status

The referral links table shows approval status:

Status	Meaning
Pending Approval	Waiting for partner to accept terms
Approved	Partner has accepted, link is active

Note

Links pending approval will not attribute any installations. The partner must approve before the link becomes active.

Resending Approval Email

If the partner didn’t receive or lost the approval email:

1. Click the ⋮ menu on the link row
2. Select Resend Approval
3. Partner receives a new email with the approval link

---

Managing Links

Viewing Links

The referral links table shows:

Column	Description
Partner	Link owner
Referral Code	The referral code
Plan	Plan hint setting
Redemptions	Count / Max
Status	Active or Inactive
Created	When the link was created

Copying the Referral Code

Click the clipboard icon next to any referral code to copy it.

Enabling/Disabling

1. Click the ⋮ menu on the link row
2. Select Enable or Disable

Deleting Links

1. Click the ⋮ menu
2. Select Delete
3. Confirm the deletion

Caution

Deleting a link removes it permanently. Historical attribution data is preserved, but the link cannot be reused.

---

Editing Links

To edit link settings:

1. Click the ⋮ menu
2. Select View / Edit
3. Update settings on the detail page
4. Changes save automatically

Note

Only non-financial settings (like the referral code or active status) can be edited. Payout terms are locked after creation.

---

Best Practices

One Link Per Campaign

Create separate links for different campaigns, even for the same partner:

• alice-podcast — For podcast mentions
• alice-youtube — For YouTube videos
• alice-twitter — For Twitter/X posts

This enables granular analytics.

Use Descriptive Referral Codes

Choose referral codes that tell you where traffic comes from:

• ✅ devto-launch-post
• ❌ link1

Set Caps for Promotions

For limited offers, set max redemptions to control exposure and create urgency.

---

Next Steps

• Link Analytics — Track link performance
• Partners Overview — Understand partner relationships