Supporting offer codes in your app

Enable customers to redeem offer codes through the App Store or within your app.

Overview

To help you acquire, retain, and win back customers, you can use offer codes. Offer codes are alphanumeric codes that provide In-App Purchases at a discount or for free, for a specific duration. Offer codes are available for all in-app purchase types: consumables, non-consumables, non-renewing subscriptions, and auto-renewable subscriptions. You can merchandise offer codes within your app or outside of it through your marketing channels.

Create and configure offer codes in App Store Connect, and distribute them to your customers. Customers can redeem offer codes throught a redemption URL, or by entering the code directly in the App Store, or within your app if it implements one of the following APIs:

offerCodeRedemption(isPresented:onCompletion:) on iOS, iPadOS, macOS, and visionOS
presentOfferCodeRedeemSheet(in:) on iOS, iPadOS, and visionOS
presentOfferCodeRedeemSheet(from:) on macOS

When customers redeem a valid offer code, your app receives a successful transaction. If customers redeem offer codes in the App Store and don’t have your app installed, they’re prompted to download it as part of the redemption flow. Successfully redeeming an offer code entitles the customer to the product, the same as a purchase does. Your app needs to provide service for the product.

Offer codes for auto-renewable subscriptions are available starting in iOS 14.2, iPadOS 14.2, macOS 15.0, and visionOS 1.0. Offer codes for consumables, non-consumables, and non-renewing subscriptions are available starting in iOS 16.3, iPadOS 16.3, macOS 15.0, and visionOS 1.0.

Set up offer codes in App Store Connect

Configure offers and manage your offer codes in App Store Connect. There are three types of offer codes: one-time use codes, custom codes, and sandbox codes for testing. The offer code redemption APIs support all offer codes types. You can have up to 10 active offers at at time, with a limit of 1,000,000 codes per app, per quarter. To distribute offer codes to your customers, download them from App Store Connect.

For more information on creating and distributing offer codes, and to learn which type of offer code may work for your campaign, see Set up offer codes and Create offer codes for in-app purchases.

Redeem offer codes in your app

To display the system sheet for customers to redeem offer codes within your app, call one of the redemption APIs, depending on your app’s UI implementation:

Call offerCodeRedemption(isPresented:onCompletion:) if your app uses SwiftUI.
Call presentOfferCodeRedeemSheet(in:) if your app uses UIKit.
Call presentOfferCodeRedeemSheet(from:) if your app uses AppKit for macOS.

The redemption sheet takes care of the redemption flow, including alerting customers about invalid entries, as appropriate. For example, an entry may be invalid if the offer code is expired or invalid, or if redeeming the code would result in a subscription downgrade.

When customers redeem an offer code, StoreKit emits the resulting transaction in updates. To ensure your app receives all the transactions that updates emits, set up the task to listen for transactions as soon as your app launches. See updates for a code example.

Including the redemption sheet in your app is recommended, but optional. For more guidance on supporting offer code redemption within your app, see Human Interface Guidelines > In-app purchase.

Support offer codes redeemed outside of your app

Customers may redeem offer codes outside your app, by entering the offer code in the App Store, or by using a redemption URL. To handle offer codes — and other transactions that can occur outside of your app — your app needs to use updates on Transaction to receive new transactions while the app is running. Create a Task to iterate through the transactions from the listener as soon as your app launches. For more information and sample code, see updates.

When your app launches, it needs to check currentEntitlements and unfinished on Transaction to get any transactions that may have occurred while the app wasn’t running. Process the transactions to ensure your app provides service for all products it’s entitled to. Call finish() after you process the unfinished transactions.

Identify products purchased with offer codes

When customers successfully redeem offer codes, the transaction contains fields that identify the offer and its offer type. Find the offer code details in the transaction information, in your app and on your server, as follows.

In your app, use the following StoreKit APIs to locate the offer code information:

Check the offer property of Transaction, and its type property. An offer type value of code indicates the customer redeemed an offer code.
If the offer code redemption applies to an auto-renewable subscription’s next renewal period, see the Product.SubscriptionInfo.RenewalInfo properties offerID and offerType. An offer type value of code indicates the customer redeemed an offer code.

On your server, use the following server-side APIs to locate offer code information:

In the App Store Server API, when you call endpoints such as Get Transaction History, Get All Subscription Statuses, and others, the response contains the signed transaction, JWSTransaction. In its decoded payload, JWSTransactionDecodedPayload, look for the fields offerIdentifier and offerType. An offerType value of 3 indicates the customer redeemed an offer code.
You receive a notification on your App Store Server Notifications V2 endpoint if someone redeems an offer code. The notificationType is OFFER_REDEEMED when someone redeems an offer for an active auto-renewable subscription; SUBSCRIBED when they redeem the offer code as an initial purchase or to resubscribe. The notificationType is ONE_TIME_CHARGE when someone redeems an offer code for a consumable, non-consumable, or non-renewing subscription product type. The decoded payloads JWSTransactionDecodedPayload and JWSRenewalInfoDecodedPayload contain the fields offerIdentifier and offerType.

Provide service to new and existing customers

When you acquire new customers with an offer code, they already have an In-App Purchase when they open your app for the first time. In addition to enabling that In-App Purchase, you may need to update your backend system’s records. Your app follows these steps:

When the app launches, check currentEntitlements and unfinished on Transaction to get the current entitlements and any new consumable transactions, respectively. StoreKit automatically validates the transactions, and returns verified results in VerificationResult.verified(_:). To perform your own validation, use the jwsRepresentation property.
To determine whether a transaction includes an offer code redemption, check the offer property of Transaction and type property of offer.
Provide the service or product based on the offer, and call finish() on Transaction.
Guide new customers through your new-user experience, as needed. Update your backend system’s records.

When an existing customer redeems an offer code within your app, the transaction comes in through the updates sequence on Transaction. Process the transaction as usual, providing service based on the offer, and call finish().

Test offer codes in the sandbox environment

You can test your app’s handling of offer codes in the sandbox environment for all In-App Purchase product types: consumable, non-consumable, non-renewing subscription, and auto-renewable subscription. First, create offer codes for the sandbox environment in App Store Connect. For more information on creating these codes, see Create offer codes for in-app purchases. Each quarter, you can create up to 10,000 codes for testing.

To redeem an offer code in the sandbox environment, follow these steps:

On your device, sign in using a Sandbox Apple Account.
On the Sandbox Account Settings page, tap Initiate Transaction.
Select Offer Codes and redeem a sandbox offer code you created in App Store Connect.

If your app supports redeeming offer codes in your app, test redeeming a sandbox offer code from your app. Navigate to the redemption sheet in your app and enter the offer code.

The sandbox environment operates with these conditions:

It doesn’t enforce a redemption limit for a Sandbox Apple Account. This means you can test multiple offer codes using the same testing account.
It ignores eligibility criteria for offer codes for consumable, non-consumable, and non-recurring subscription product types.
It applies eligibility criteria to offer codes for auto-renewable subscriptions. To test subscription offer codes again, clear the sandbox account purchase history. For more information, see Manage Sandbox Apple Account settings
It verifies whether an offer code is available in the storefront of the Sandbox Apple Account.

On your server, App Store Server Notifications notifies you of offer code redemptions in the sandbox environment if you enable a notifications endpoint for the sandbox environment. For more information, see Enabling App Store Server Notifications.

For more information on sandbox testing, see Testing In-App Purchases with sandbox.

Supporting systems earlier than iOS 16 and iPadOS 16

If your app runs on iOS 16 or earlier, and iPadOS 16 or earlier, you can support offer codes for auto-renewable subscriptions only. Use presentCodeRedemptionSheet() to display the offer code redemption UI. Otherwise, use the APIs referred to in this article. For more information about supporting earlier systems, see Implementing offer codes in your app.