Tracking affiliate-driven upgrades in a freemium app requires linking a user's original affiliate referral to the moment they convert from a free plan to a paid one. The gap between install and upgrade can be days, weeks, or even months, which makes this one of the trickiest attribution problems in mobile affiliate marketing. Here is how to solve it.
Why Freemium Upgrade Tracking Is Different
In a standard affiliate setup, the conversion event happens almost immediately: a user clicks a link, installs the app, and makes a purchase. Freemium apps break that pattern. The user installs for free, uses the app at no cost, and only later decides to upgrade. The median freemium-to-paid conversion rate sits around 2-5%, meaning only a small percentage of free users ever become paying customers. That makes accurate attribution even more important because every paying upgrade is valuable.
The core challenge is persistence. You need to store the affiliate identifier at the moment of first install and preserve it until the upgrade event fires, no matter how much time passes.
Step 1: Capture the Affiliate Identifier at Install
When a user taps an affiliate link, the link should carry a unique affiliate identifier. On iOS, universal links pass this identifier directly to your app on launch. On Android, app links do the same. If the app is not yet installed, deferred deep linking ensures the identifier is recovered after the user downloads and opens the app for the first time.
The critical action at this stage is storing that affiliate identifier server-side, tied to the user's account or anonymous device profile. Do not rely solely on local device storage. If the user switches devices, reinstalls, or clears app data, a locally stored identifier is lost.
Step 2: Persist the Affiliate Relationship in Your Backend
Once the affiliate identifier reaches your server, associate it with the user record in your database. This creates a permanent link between the user and the affiliate who referred them. Every subsequent monetisation event for that user can then be checked against this stored relationship.
A simple schema looks like this:
- users table: user_id, email, created_at
- affiliate_referrals table: user_id, affiliate_id, referral_date, referral_source
When the user upgrades, your backend already knows which affiliate referred them because the relationship was stored at sign-up time.
Step 3: Detect the Upgrade Event
The upgrade event can come from several sources depending on your payment stack:
- Apple App Store and Google Play Store: Server-to-server notifications (App Store Server Notifications v2 or Google Real-Time Developer Notifications) fire when a subscription is purchased or an in-app purchase is completed.
- RevenueCat: Webhook events such as INITIAL_PURCHASE or PRODUCT_CHANGE indicate that a user has moved from a free tier to a paid subscription. Most RevenueCat webhooks arrive within 5 to 60 seconds of the event.
- Stripe: If you process payments through Stripe (for web billing or external payment flows), webhook events like checkout.session.completed or customer.subscription.created signal the upgrade.
Each of these events includes a user identifier that you can match against your affiliate_referrals table.
Step 4: Attribute the Upgrade to the Affiliate
When the upgrade event arrives, your server performs a lookup: does this user_id exist in the affiliate_referrals table? If yes, the upgrade is attributed to that affiliate, and a commission record is created.
You should also consider setting an attribution window. Common windows range from 30 to 90 days for freemium apps, though some programs use longer windows given the naturally slow conversion cycle. If a user upgrades 14 months after installing, you need to decide whether the affiliate still deserves credit.
Step 5: Handle Edge Cases
Real-world tracking introduces several edge cases that your system needs to handle:
- Multiple affiliates: If a user clicks links from two different affiliates before upgrading, you need a rule. Last-click attribution is the simplest approach, crediting the most recent affiliate. First-click attribution rewards the affiliate who originally introduced the user to the app, which is often more appropriate for freemium models where the initial discovery matters most.
- Trial-to-paid transitions: If your freemium app offers a free trial of premium features before requiring payment, the true conversion event is the end of the trial when the user is first charged, not the start of the trial.
- Upgrade tiers: A user might upgrade from free to a basic plan, then later to a premium plan. Decide whether the affiliate earns commission on only the first upgrade or on subsequent upgrades as well.
Step 6: Configure Commission Triggers
With the attribution data in place, you need to define what triggers a commission payout:
- Percentage of first payment: The affiliate earns a percentage of the user's first paid transaction. This is the simplest model.
- Recurring percentage: The affiliate earns a percentage of every payment the user makes for a defined period or for the lifetime of the subscription. This incentivises affiliates to refer users who will stick around.
- Flat fee on upgrade: The affiliate earns a fixed cash amount when the upgrade occurs, regardless of the plan price.
Insert Affiliate handles all of these commission structures and pays affiliates in cash via Stripe, so there is no need to build your own payout system.
Using Insert Affiliate for Freemium Upgrade Tracking
Insert Affiliate's SDK captures the affiliate identifier at install time and persists it through your payment stack. When a user upgrades from free to paid, the platform automatically attributes that conversion to the referring affiliate and calculates the commission based on your configured rules.
The platform integrates with RevenueCat, Stripe, and direct App Store and Google Play Store server notifications. This means you do not need to build custom webhook handlers or maintain your own affiliate_referrals table. The SDK and dashboard handle the full lifecycle from click to commission.
Insert Affiliate offers both flat-fee and revenue-share pricing plans, and affiliates sign up through a dedicated signup page. SDKs are available for Swift, Kotlin, React Native, Flutter, Unity, and JavaScript.
Key Metrics to Monitor
Once your tracking is live, monitor these metrics to evaluate affiliate performance in the freemium context:
- Time to upgrade: How long do affiliate-referred users take to convert from free to paid compared to organic users?
- Upgrade rate: What percentage of affiliate-referred free users eventually upgrade? If it is significantly lower than organic, your affiliates may be targeting the wrong audience.
- Lifetime value (LTV): Do affiliate-referred paying users retain and spend at the same rate as organic paying users?
- Commission-to-LTV ratio: Ensure the commissions you pay are sustainable relative to the revenue each referred user generates.
Tracking affiliate-driven upgrades in a freemium app is more complex than tracking simple install-to-purchase flows, but the payoff is worth it. By persisting the affiliate relationship from the moment of first install and connecting it to your payment events, you give affiliates confidence that their long-term promotion efforts are being rewarded accurately.