Let's journey through set up, redemption, and tracking
January 11, 2022
January 11, 2022
Offer Codes are a type of iOS Subscription Offer that allow you to present free or discounted prices for auto-renewable subscriptions through single-use redeemable codes. Depending on how they’re configured in App Store Connect, offer codes can be presented to new, existing, or lapsed subscribers to drive further engagement with your app.
Note that in order to redeem your offer codes, subscribers must be running iOS 14+ or iPadOS 14+. MacOS is currently not supported.
How do I set up Offer Codes for a subscription?
You can configure and generate offer codes for a subscription in your app settings in App Store Connect (in the Subscription Pricing menu for your product). Check out RevenueCat’s guide or Apple’s Help Center article for help with this process.
Once you’ve generated and downloaded the offer codes, you’re responsible for distributing them to subscribers through your own systems (such as through email or other marketing campaigns). You can either share the codes directly or distribute URLs with the codes embedded to your subscribers.
Keep in mind that offer codes expire six months after they’ve been generated, unless you set an earlier expiration date (or if you deactivate them, in which case they will expire immediately—see this Help Center article to learn more about deactivating offer codes).
Is there any additional setup required in RevenueCat?
The only configuration RevenueCat needs is a subscription key, which is required to validate API requests associated with Apple offer codes. Check out our guide on how to download a subscription key from Apple and upload it to RevenueCat.
How are Offer Codes redeemed?
Redeeming on the App Store
Subscribers can redeem offer codes directly on the App Store (through the Redeem Gift Card or Code page in their account settings), or you can provide them a URL with the code embedded. This will take them to the App Store flow with the code already entered.
If the subscriber doesn’t have your app installed, the app will be installed automatically as part of the redemption flow.
Redeeming from your app
If you choose to support it, subscribers can also redeem offer codes from your app. On a paywall, for example, you can add a button called Redeem Offer, which will call the function presentCodeRedemptionSheet(). We expose this function through our SDK on all platforms, but the code will only present the sheet on iOS devices.
This function call will guide the user through a redemption flow similar to the one on the App Store, and is dictated by Apple, not by your app or by RevenueCat. You can see a sample UI for this flow below (from Apple's docs):
How should my app respond to these purchases?
These redemption flows occur within an external interface dictated by Apple, so a transaction will be placed on the SKPaymentQueue to be finished by your app. For this reason, Apple recommends initializing a transaction observer as soon as your app launches. Fortunately, RevenueCat’s SDK takes care of this for you by attempting to finish any pending transactions whenever the app is launched or foregrounded.
But there is a caveat with using presentCodeRedemptionSheet(): because this function has no callback, there isn’t a convenient way to know whether a redemption was carried out successfully or if the flow was canceled. Because of this, we recommend implementing our PurchaserInfo listener so your app will be notified when a user gains an entitlement through a redemption.
Once redeemed, when do Offer Codes go into effect?
When an offer code goes into effect depends on how you’ve configured it in App Store Connect, and on the subscriber’s current status. For new and lapsed subscribers, if you’ve added an introductory offer to your subscription, you can configure whether the subscriber can redeem both offers or only the offer code:
If you allow both, and assuming the subscriber is eligible, the introductory offer will go into effect immediately and the offer code will be applied after the introductory offer ends. See the illustrations below, taken from Apple’s Tech Talk video:
If you don’t allow both, the offer code will be applied immediately and the introductory offer will still be available in the future:
For existing subscribers, if the offer code is for their current subscription, it should go into effect at the next renewal. If the offer code is for a different subscription in the same subscription group or a higher-tiered subscription group, it should go into effect either immediately or at the next renewal, depending on upgrade or crossgrade behavior.
How can I track purchases made with Offer Codes in RevenueCat?
You can keep track of purchases made with offer codes by setting up webhooks for your app in RevenueCat. Transaction events come with a field offer_code that will list the offer code used for the purchase (corresponding to the reference name you’ve set in App Store Connect), or null if no offer code was used.
Note that prices for all transactions made with offer codes will be tracked as $0 in RevenueCat’s dashboard, due to limited data provided by Apple at this time.
It seems offer codes cannot be tested in sandbox at this time, so you will need to test in production. If you try testing your redemption flow in sandbox, you may receive an error message that says the offer code has already expired.
Offer codes only work for crossgrades and upgrades, not downgrades. If a subscriber tries to redeem an offer code for a subscription at a lower level than their current subscription, they will receive an error message that the offer code can’t be redeemed with their current subscription.
Be aware that when you’re configuring your offer code eligibility for new, existing, or lapsed subscribers, Apple checks if the subscriber is new, existing, or lapsed for the entire subscription group, not just the subscription the offer code is for.
Subscribers who redeem a code but have no record of purchases in RevenueCat will need to restore purchases to sync their device receipt with RevenueCat and unlock the entitlement for their current App User ID in your app.