Offer Codes

Offer codes let you reward referred users with discounts by automatically distributing App Store or Play Store promo codes when attribution occurs.

---

What Are Offer Codes?

Offer codes are promotional codes generated in App Store Connect (Apple) or Play Console (Google) that give users discounts on subscriptions or in-app purchases.

• Apple: Set up subscription offer codes
• Google: Create and manage promo codes

BitEasy lets you:

1. Upload these codes to a referral link
2. Automatically distribute a code when /claim succeeds
3. Return the code in the API response for your app to redeem

---

How It Works

flowchart TB
    A[Upload codes to referral link] --> B[User claims attribution]
    B --> C["/claim returns offer code"]
    C --> D[Your app user redeems the code]
    D --> E[User gets discount]

1. Export codes from App Store Connect or Play Console (CSV format)
2. Upload codes to a referral link in BitEasy
3. When a user is attributed via /claim, BitEasy returns an offer code in the response
4. Your app implements the logic to redeem or display the code to the user

---

Uploading Offer Codes

1. Navigate to your app → Referral Links
2. Click on a referral link to edit it
3. Go to the Offer Codes tab
4. Click Upload Codes
5. Select your CSV file exported from App Store Connect or Play Console
6. Codes are imported and ready to distribute

Tip

Export codes as CSV from App Store Connect (Promo Codes) or Play Console. BitEasy will parse the file automatically.

---

Matching Codes to Plans

If your referral link has a plan hint selected (e.g., monthly or yearly), your uploaded offer codes should match that plan:

Link Plan Hint	Offer Codes Should Be
Monthly	Monthly subscription promo codes
Yearly	Annual subscription promo codes
Any	Any codes (but consider organizing by link)

Caution

Mismatched codes (e.g., a yearly code on a monthly link) may confuse users or fail to redeem properly.

---

The /claim Response

When attribution succeeds and an offer code is available, the /claim response includes it in the paywall object:

{
  "status": "claimed",
  "referrer": "alice-yearly-2026",
  "path": null,
  "paywall": {
    "id": "default",
    "source": "partner",
    "partner": "alice",
    "offerCode": {
      "code": "PROMO-ABCD-1234-EFGH",
      "platform": "ios",
      "subscriptionDuration": "yearly",
      "expiresAt": "2026-12-31"
    }
  }
}

Your app should:

1. Check if paywall?.offerCode is present in the response
2. Display the code to the user, or
3. Automatically apply it using the platform’s redemption API

---

Implementing Code Redemption

iOS (Swift)

Redirect to the App Store offer code redemption URL:

if let offerCode = claimResponse.paywall?.offerCode {
    // Open App Store redemption page
    // Replace APP_ID with your App Store app ID (numeric)
    let urlString = "itms-apps://apps.apple.com/redeem?ctx=offercodes&id=\(appId)&code=\(offerCode.code)"
    if let url = URL(string: urlString) {
        UIApplication.shared.open(url)
    }
}

Android (Kotlin)

Deep link to the Play Store redemption page:

claimResponse.paywall?.offerCode?.let { offerCode ->
    val intent = Intent(Intent.ACTION_VIEW).apply {
        data = Uri.parse("https://play.google.com/redeem?code=${offerCode.code}")
    }
    startActivity(intent)
}

React Native

Use an in-app browser to keep users in your app:

import { Platform, Linking } from 'react-native';

async function redeemOfferCode(claimResponse: ClaimResponse) {
  const offerCode = claimResponse.paywall?.offerCode;
  if (!offerCode) return;

  const url = Platform.select({
    // Replace APP_ID with your App Store app ID (numeric)
    ios: `itms-apps://apps.apple.com/redeem?ctx=offercodes&id=${appId}&code=${offerCode.code}`,
    android: `https://play.google.com/redeem?code=${offerCode.code}`,
  });

  if (!url) return;

  Linking.openURL(url);
}

---

Monitoring Your Codes

Keep an eye on your offer codes inventory:

Metric	Description
Available	Codes ready to distribute
Distributed	Codes already given out
Expiring Soon	Codes expiring within 7 days
Expired	Codes that can no longer be redeemed

Don't Run Out!

If all codes are distributed or expired, /claim will still succeed but won’t return an offer code. Monitor this tab and upload new codes before you run out.

---

Best Practices

Keep Codes Topped Up

• Check the Offer Codes tab regularly
• Upload new batches before running out
• Set calendar reminders for expiring codes

Match Codes to Campaigns

Create separate referral links for different offers:

• alice-yearly-50off → Upload yearly 50% off codes
• alice-monthly-trial → Upload monthly free trial codes

Handle Missing Codes Gracefully

Your app should handle the case where no offer code is returned:

const offerCode = claimResponse.paywall?.offerCode;
if (offerCode) {
  showOfferRedemption(offerCode.code);
} else {
  // Still attributed, just no offer code available
  showWelcomeScreen();
}

---

FAQ

What happens if codes run out?

Attribution still works — the user is still credited to the partner. The only difference is that /claim won’t include an offerCode in the response.

Can I use the same codes for multiple links?

No. Each code can only be uploaded to one referral link. If you need the same offer on multiple links, export enough codes for each.

Do codes expire?

Yes. App Store and Play Store codes have expiration dates. BitEasy tracks this and shows you which codes are expiring soon.

---

Next Steps

• Creating Links — Set up referral links
• Link Analytics — Track redemption rates