A Guide to Implement Offer Codes in iOS

Published in

Simform Engineering

8 min readAug 9, 2023

A Complete Step-by-Step Guide to iOS Offer Codes, from Implementation to Testing.

Offer codes can be applied to in-app purchase auto-renewable subscriptions. These codes let you give subscriptions at a discounted price or for free, valid for a specified duration. These details are specified when creating the offer code in App Store Connect.

Integrating offer codes into applications can be challenging. It requires a clear understanding of their functionality and testing methodology. In this blog, we will go through the process of creating and implementing offer codes step by step, along with some testing notes.

Pre Requirement

Before proceeding, make sure you’ve already integrated the auto-renewable in-app purchase within your app. If you haven’t done that yet, I recommend referring to Apple’s official documentation on auto-renewable in-app purchases.

Create an offer code category on Appstore Connect

Go to Appstore Connect.
Select your app.
In the right sidebar Features menu, select the Subscription option.
Select your subscription group.
Select the subscription type to which you want to add the offer code.
Scroll down to the Subscription Prices section and click View all Subscription Pricing.

[Scroll to View all Subscription Prices and click on it]

7. Click on the offer code.

8. Select plus button, and it will redirect to the below screen.

9. Add offer reference name:

All types of codes for an annual subscription will be grouped under one reference name.
When making a request to the Apple verifyReceipt API, this reference name will be included in the response.

10. Customer Eligibility: Select which user can redeem the offer code. You can select multiple options here.

New subscription: The user has not purchased any subscription before.
Existing subscription: The user currently has an active subscription.
Expired subscription: The user previously had a subscription, which is expired now.

11. Introductory Offers: This option is useful when you have an introductory offer as well.

Yes: Users will receive both the introductory offer and the subsequent offer from the offer code, with the introductory offer taking precedence.
No: User will get offer code offer only.

12. Click Next, and it will redirect to the Countries or Regions screen, where you can select which country is eligible for this offer code.

[country and regions selection for offer code]

13. Click Next to redirect to the Type of Offer Screen.

There are three types of payment for offer:

Pay as you go: Users pay a discounted price for each billing period for a selected duration.

Pay Up Front: Users pay a one-time discounted price for a selected duration.

Free: Users access the subscription for free for a selected duration.

Check out this official Apple doc for more details about the payment type of offer.

[Reference from Apple’s official document for pricing and availability]

Now depending on the type you select, they ask for some more details like the duration and price of the offer. Fill in those details (in our example, I selected ‘free for the 1-month duration’) and click Next.

14. Validate the Offer Price for each region and click on Confirm. The offer code category is successfully created now and will be displayed as shown:

[Select region for offer code validation]

We have created an offer category; we are now halfway there.

[One-month free offer code category is created]

Now we will create actual offer codes. Select your newly created offer category; in our case, it’s One month free.

[Details on One-month free offer code category]

Before creating any offer code, first, let’s understand its types.

Types of Offer Codes

There are two types of offer codes:

One-time use code
Custom code

Note: You can create codes for a maximum of 150,000 redemptions per app, per quarter.

Create a One-Time offer code

A one-time offer code is a unique numerical code that can only be used once. These codes are useful for small-scale distribution or when code access needs to be restricted.

To create a one-time code, follow these steps:

Click on the “One-Time” code option.
Add the number of codes you want to create.
Set the expiration date for these codes.

Note: One-time codes can have a maximum expiry period of 6 months.

Once you create a one-time code, a file will be generated containing a downloadable link. This link comprises URLs for all the codes you’ve created.
An example of such a URL: https://apps.apple.com/redeem?ctx=offercodes&id=1567167661&code=MHNAJMLTR6RJN338K4
In this URL, the ‘Id’ represents the App ID, and the ‘code’ is a unique, one-time-use code.

This one-time code offer can be redeemed in three ways:

Share the URL with your users, either online or offline. They can redeem it by simply clicking on the URL.
Provide the code itself (which you can find at the end of the URL, such as MHNAJMLTR6RJN338K4 ) with the user. In the App Store, users can go to the Gift Card or Code section and input this code to redeem the offer.
If you’ve implemented a redeem feature within your app (as covered in the next section), users can also redeem codes directly within the app.

Create Custom offer code

A single Custom code (like “Flat20” or “BOGO50”) is generated and can be distributed to a large number of users. Its redemption limit is set while creating the code.
Custom codes can contain only alphanumeric characters and can’t be used for other offer campaigns or subscriptions for this app.

To create a custom code, follow these steps:

Click on “Custom code.”
Provide a unique name for the Custom code (such as “Discount20” or “Flat20”).
Specify the number of times the code can be redeemed through the Redemption Limit.
Set an expiration date.
Click on “Create.”

Note: It may take some time, an hour or so, before codes become redeemable by users.

Custom code can be redeemed in two ways:

Using the offer code URL: share the URL of the offer code as mentioned below with the user, and they can redeem it by clicking on the URL.
Within the app, if you’ve incorporated a redeem feature (which we’ll cover in the next section).

To share Custom Code as URL, use the URL found on the offer category as shown below and just replace the CODE part with actual code e.g., BOGO50

Note: Users cannot redeem a custom code through the App Store’s Gift Card or Code section. This is due to the common nature of custom code names used within many app’s offer codes, making it impossible to identify the specific apps associated with them.

Implement a code redemption feature inside the app

Create a UI for your Redeem button where you intend your users to redeem their codes. Typically, this button is placed alongside the upgrade section.

[Example to Use your custom Redeem button UI]

To initiate the process of code redemption, call presentCodeRedemptionSheet().

[ code to open offer code redemption sheet ]

This function will open Apple’s default redeem sheet for the user, as shown below:

Note: we can not modify UI for redemption sheet, we can only use default sheet for code redemption.

Within this sheet, the user can enter the code and proceed with the redemption process, which includes handling any necessary payments. This entire procedure is managed by Apple’s systems.
Once the redemption process is finished, a callback will be received in the payment queue.
Handling this callback won’t require any extra effort; it will resemble the callbacks received for a regular in-app purchase payment flow.

Deactivate code

To create a custom code already being used by a different offer for the same app, you must first deactivate the code.
To deactivate a specific code, locate the code and click on the “Deactivate” button on the right side of the code entry.
To deactivate the entire offer code category, click the Deactivate button in red font, as shown in the image.

Testing notes

Currently, we can not test offer codes with a sandbox environment. (Source)
One option to test offer code, other than in a production environment, is to use Storekit testing.

Configure StoreKit in Xcode for offer code testing

Create new file> Storekit Configuration file> Select team and App> Sync> Next> Location > Save.

[Sync local store kit testing file with Appstore Configuration]

2. Select the newly created Storekit file> Edit > Save Public Certificate.

[Create public certification for local validation]

3. Edit Schema> Run > Options > Storekit Configuration> Select Storekit file.

[Prepared store kit testing setup at the run time]

4. Run app > Open Storekit Manager from debug area.

[Open store kit manager to see testing transaction]

5. Start the Redeem process and see the logs on Storekit Manager.

[Transaction log on store kit manage]

Note: As store kit testing is local testing only, we suggest testing the offer code in the production environment as well once the app is available on Appstore before distributing offer codes to the user.

Receipt validation with offer code

If a user makes a purchase using an offer code, the receipt will contain a transaction with the field: offer_code_ref_name.
To validate the receipt, you can extract offer_code_ref_name from responseBody.Latest_receipt_info and responseBody.Pending_renewal_info objects found in the receipts response.
Once extracted, you can store offer_code_ref_name in your database.
Use this stored offer_code_ref_name for further processes, such as tracking which offer code is redeemed the most and which users used an offer code for subscription purchases.

Conclusion

Offer codes provide a powerful way to acquire new subscribers and retain existing ones by providing special discounted or free access. With a clear understanding of how to implement offer code redemption within your iOS app, you can take full advantage of this App Store Connect feature.

Be sure to follow best practices around testing with the local environment in Xcode and the production environment. Then analyze offer code usage to continuously refine your subscription marketing strategy. When implemented thoughtfully, offer codes can become an integral tool for growing a loyal subscriber base for your app.