Referral programs for subscription apps
A subscription app referral program credits the person who invited a new subscriber and rewards the inviter with time on their plan. We match installs that follow a tap on a referral link to the inviter and send your backend a signed referral.claimed webhook. Your backend grants the free month through the store or your entitlement service.
How it works
Give each subscriber a referral link
Create a link for your app with Referral link turned on, one for each subscriber. Store its link id with the user record, so a later claim points back to the person who invited.
Reward the inviter, not the install
Plan the free month for the person who invites. Read the store rules for referral rewards before you offer the invited person anything, and describe the program in your App Review notes.
Claim after the account exists
Show the invitation page, then read the invitation at first launch. Once the new user has an account, call claimReferral with your own id for that user, so the reward waits for a real sign-up.
Verify the referral.claimed webhook
Check the signature, skip event ids you have handled, and read data.match.exact. Look up the inviter from data.link.id, which you stored in the first step.
Grant the month through the store
Use an Apple promotional offer or offer code, a Google Play promo code, or an entitlement service. Record the event id with the grant, so a retry or resend grants only once.
Watch results in the Referrals report
The Referrals report lists each credited referral with its match and status, next to your other link analytics. REST and MCP return the same data.
Read the invitation and claim it
import WarpLink
// First screen: offer the invitation paste.
WarpLinkPasteButton { result in
if case .success(let link) = result, link != nil { showInvitationApplied() }
}
// After sign-up: credit the invite with your own id for the new user.
WarpLink.claimReferral(installerId: user.warplinkId) { result in
guard case .success(let claim) = result, claim.status == .claimed else { return }
// Recorded. Your webhook grants the reward.
}// Nothing to paste on Android: the Play install referrer carries the invitation.
// After sign-up: credit the invite with your own id for the new user.
WarpLink.claimReferral(user.warplinkId) { result ->
result.onSuccess { claim ->
if (claim.status == ReferralClaimStatus.CLAIMED) {
// Recorded. Your webhook grants the reward.
}
}
}What you get
- Linking
- A referral link for each subscriber on your app's aplnk.to address or a custom domain, and an invitation page for iPhone visitors who do not have the app yet.
- Attribution
- Each claim credits the install that follows a tap on the referral link. Exact matches come from the install token, the Android referrer or a link open, and an exact claim replaces an earlier estimate.
- Analytics
- The Referrals report lists claims newest first, with status and match method. The same data is on REST at GET /v1/referrals and over MCP with list_referrals.
Common questions
Who gets the free month?
You decide in your own backend. Apple reviewers have written that rewarding the inviter is acceptable and that the invited person should not be rewarded for downloading or registering. Read the current store guidelines before you design the reward.
Do you grant the subscription time?
No. We credit the install and send a signed webhook. Your backend grants the month with Apple offers, Google Play promo codes or an entitlement service such as RevenueCat.
When does the reward trigger?
Your app calls claimReferral after the new user has an account, so the webhook arrives after a sign-up and not after a tap or a download. Your backend then applies your own rule.
How do I avoid granting twice?
Store the webhook event id with each grant and skip an id you have seen. The id stays the same across retries. The first valid claim for an installer is the only one credited.
Does it work on iPhone and Android?
Yes. Android reads the invitation from the Play install referrer. On iPhone, the invitation page and the system paste button carry it through the App Store. Use SDK 1.2.0 or later.