Engineering

Create and Track Offer Codes for Your iOS App

Let's journey through set up, redemption, and tracking

How Do Apple Offer Codes Work?
Sunny Manik
Sunny ManikJanuary 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. 

The URL template looks like this:
https://apps.apple.com/redeem?ctx=offercodes&id={app ID}&code={offer code}

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):

A sample of Apple’s redemption flow when triggered from your app

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: 

This option is available in the menu for creating offer codes.

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:

An introductory offer for one free week is followed by an offer code for one free week. 

If you don’t allow both, the offer code will be applied immediately and the introductory offer will still be available in the future: 

The offer code for one free week is applied alone. The introductory offer can only be redeemed if the user re-subscribes later.

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 monitor 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.

Other considerations:

  • 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.
  • Some developers have reported that their subscribers are unable to redeem an offer code while a free trial is currently active. It’s unclear if this is related to how you’ve configured your offer code + introductory offer behavior, or if it’s due to some other behavior undisclosed by Apple. If you run into an issue like this, advise the subscriber to wait until the trial is over to redeem the code.

Further reading

Subscribe to our monthly newsletter

Related posts

Google Play class action developer lawsuit
Engineering

Google Play Billing Library 5.0, an overview

Everything you need to know about Google Play Billing Library 5

Rik Haandrikman

Rik Haandrikman

November 25, 2022

Engineering

How RevenueCat’s SDK team uses Release Trains

How we automate the releases of our SDKs

Cesar de la Vega

Cesar de la Vega

October 31, 2022

Stripe for In-App Purchases
Engineering

Can You Use Stripe for In-App Purchases?

Learn about when you can use Stripe and opportunities to save money on fees.

Corey Rabazinski

Corey Rabazinski

October 31, 2022

Want to see how RevenueCat can help?

RevenueCat enables us to have one single source of truth for subscriptions and revenue data.

Olivier Lemarie, PhotoRoomOlivier Lemarie, PhotoRoom
Read case study