Give a Free Month for a Referral in a Subscription App

To give a free month for a referral in a subscription app, verify the signed referral.claimed webhook, find the inviter from data.link.id, and grant the month through Apple offer codes or promotional offers, Google Play promo codes, or an entitlement service. We credit the install and send the event. Your backend grants the reward.

This guide shows the whole path. You pick a trigger that proves a real sign-up, map the event to your inviter, choose a grant mechanism for each store, and record the grant once. Read the store rules for referral rewards first, because they decide who can receive the month.

Decide who gets the month

Apple reviewers have written that rewarding the invitation sender is acceptable and that the person receiving the invitation should not receive a reward for downloading or registering. The quotes, with links, are in App Store and Google Play referral reward rules. This guide grants the month to the inviter. If you want to give the invited person something too, read that post and your review notes first.

Trigger from the webhook

Your app calls claimReferral once the new user has an account, so referral.claimed arrives after a sign-up and not after a tap. The payload names the link, the installer, and the match:

{
  "id": "evt_...",
  "type": "referral.claimed",
  "data": {
    "referral_id": "...",
    "link": { "id": "...", "slug": "...", "url": "..." },
    "installer_id": "user_8841",
    "match": { "method": "install_token", "exact": true, "confidence": 1 },
    "claimed_via": "sdk",
    "flags": []
  }
}

Grant on referral.claimed when data.match.exact is true and flags is empty. An estimated match on iPhone arrives with exact: false; when the same installer later claims with an exact match we send referral.updated. Hold the estimate, and grant when referral.updated arrives with exact: true. Exact vs estimated referral matches explains the evidence, and verifying a referral before the reward covers the other checks. The receivers are in Node.js and Python.

Find the inviter

installer_id is the id your app passed to claimReferral, so it names the invited person. The inviter is the owner of the link. When you create each inviter's referral link, store its link id with your user record, then look it up by data.link.id:

const inviter = await db.users.findByReferralLinkId(event.data.link.id);
if (!inviter) return; // link not mapped to a user: nothing to grant

Grant the month

Pick the mechanism that matches how the inviter pays.

Apple promotional offers

Apple's promotional offers give lapsed or current subscribers a discounted or free period on auto-renewable subscriptions. Apple documents that "the App Store deems all customers with an existing or expired subscription in the app eligible to redeem a promotional offer," and that "you decide the criteria for which subscribers qualify." Your server signs each offer with a key from App Store Connect, and the signature is "time sensitive, unique per offer, and redeemable only once."

That fits an inviter who already subscribes. After the webhook, mark the inviter as eligible in your database. When the inviter opens your app, your server returns the signed offer, and the inviter confirms it in the purchase sheet. Apple notes the offer period starts at the next billing event, and a user can have only one promotional offer active at a time.

Apple offer codes

Offer codes are "alphanumeric codes that provide Apple In-App Purchases at a discount or for free, for a specific duration." You create them in App Store Connect, with up to 10 active offers and 1,000,000 codes per app per quarter. Customers redeem a code through a redemption URL, in the App Store, or in your app with the system redemption sheet.

For a referral reward, download a pool of one-time codes, and after the webhook assign one unused code to the inviter. Show it in the app or send it by email. Apple's server notifications tell you when it is redeemed: OFFER_REDEEMED for an active subscription, SUBSCRIBED for an initial purchase or a resubscribe.

Google Play promo codes

Google Play promo codes for subscriptions "provide users with a free trial of between 3 and 90 days." You can create one-time use codes, limited to 10,000 per quarter per subscription product, and custom codes, which "can only be redeemed by users who have not previously subscribed." A 30-day code is a free month for an inviter who has not subscribed. Assign one one-time code per event, the same way as an Apple code pool. For an inviter who already subscribes on Android, grant the month through an entitlement service, below.

An entitlement service

If a service manages entitlements for your subscription app, your backend can grant access after the verified event. RevenueCat documents promotional entitlements that you can grant to a customer from the dashboard, and a REST endpoint for the same grant. A free month is an end_time_ms thirty days ahead:

async function grantFreeMonth(appUserId) {
  const endTimeMs = Date.now() + 30 * 24 * 60 * 60 * 1000;
  const res = await fetch(
    `https://api.revenuecat.com/v1/subscribers/${encodeURIComponent(appUserId)}/entitlements/premium/promotional`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.REVENUECAT_SECRET_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ end_time_ms: endTimeMs }),
    },
  );
  if (!res.ok) throw new Error(`Grant failed: ${res.status}`);
}

premium is the entitlement identifier you configured, and appUserId is the id you gave the service for the inviter. Guideline 3.1.1 says apps "may not use their own mechanisms to unlock content or functionality," so check the guideline for your case before you grant access outside the store.

Record the grant once

Delivery is at least once, so the same event can arrive twice. Store the event id before the grant to claim it, and delete the row if the grant fails, so the retry can try again:

async function handleReferralEvent(event) {
  if (event.type !== 'referral.claimed' && event.type !== 'referral.updated') return;
  if (!event.data.match.exact || event.data.flags.length > 0) return;
  const inserted = await db.grants.insertIfNew(event.id, event.data.link.id);
  if (!inserted) return; // already granted for this event
  try {
    const inviter = await db.users.findByReferralLinkId(event.data.link.id);
    if (inviter) await grantFreeMonth(inviter.id);
  } catch (err) {
    await db.grants.delete(event.id); // free the id so the retry can grant
    throw err; // answer 5xx so the delivery is sent again
  }
}

A failed grant answers with a 5xx, so we send the delivery again, up to 5 attempts, and the handler tries again each time.

Return a 2xx within 10 seconds. If the grant can take longer, answer 200 at once and run the grant from a queue or job, so a slow grant that fails is retried by your own worker and not lost. A second claim for the same installer is recorded as a duplicate and sends no webhook. An exact claim that follows an estimate sends referral.updated, so one invited person earns one grant.

Frequently Asked Questions

How do I give a free month as a referral reward in a subscription app?

Verify the signed referral.claimed webhook, find the inviter from data.link.id, and grant the month through offer codes, promotional offers, promo codes, or an entitlement service. We record the referral and send the event. Your backend grants the reward.

Which Apple mechanism fits an inviter who already subscribes?

A promotional offer. Apple deems customers with an existing or expired subscription in your app eligible, and you decide any further criteria. Your server signs each offer, so the grant happens only after your backend approves it.

Can I use an offer code for the invited person?

Apple documents offer codes as a way to acquire customers, and Google Play documents promo codes for people who have not subscribed. Reviewers have objected to rewards for the invited person, so read the referral reward rules before you build it.

Does RevenueCat work with this flow?

Yes. RevenueCat documents a promotional entitlement you can grant from its dashboard or its REST API. Your backend calls it after the verified webhook arrives.

How do I avoid granting the month twice?

Store the event id with each grant and skip an id you have seen. The id is the same on every retry and every resend.

Related Guides

• Rules first: App Store and Google Play referral reward rules.
• Reference: Referrals and Receive referral webhooks.
• Receivers: Node.js and Python.
• Checks before paying: Verify a referral install before you grant the reward.
• Use case: Referral programs for subscription apps.

How WarpLink Helps

We do the matching and keep the record. A referral link carries the invitation, install attribution credits the install that follows a tap on that link, and the Referrals report shows each credited referral beside your other link analytics. The signed webhook hands your backend one event per credited sign-up, and your subscription logic does the rest.

Create a free WarpLink account and get deep linking, install attribution, and real-time analytics in one SDK, with 10,000 clicks a month on the free plan.