Create and track offer codes for your iOS app
Offer codes give you a controlled way to present a free or discounted price for an auto-renewable subscription. Each code is single-use, you create and distribute the codes yourself, and you can target new, existing, or lapsed subscribers depending on the configuration.
What offer codes are and how to create them
Think of an offer code as a one-time ticket tied to a subscription price. You generate a batch in App Store Connect, then deliver codes through your own channels such as email or a campaign link. A code can carry the code directly, or a link can embed it so the App Store opens with the code already filled in. Eligibility is set at the subscription-group level: Apple checks whether the person is new, existing, or lapsed across the whole group, not only for the single subscription named on the code. Plan expiry before you generate: codes last six months by default, an earlier date can be chosen, and deactivation ends them immediately. Redemption requires iOS 14+ or iPadOS 14+; macOS is not supported.
Setup checklist: App Store Connect and subscription key
Create the codes from the subscription pricing area for your product in App Store Connect, download the generated batch, and distribute them yourself. For validation of Apple offer-code API requests, upload a subscription key obtained from Apple. That upload is the only additional configuration needed on the subscription-management side. Keep the reference name you assign in App Store Connect, because that same name is what later appears in tracking data.
Redemption paths and how your app should react
Subscribers have two paths. In the App Store, they can use the Redeem Gift Card or Code page in account settings, or open a link built from the redeem template https://apps.apple.com/redeem?ctx=offercodes&id={app ID}&code={offer code} with the app ID and code filled in; if the app is not installed, installation happens as part of the flow. Inside your app, you can add a Redeem Offer button on a paywall that calls presentCodeRedemptionSheet() to present Apple's redemption sheet. That function is exposed through the SDK on all platforms, but it only presents the sheet on iOS devices. The sheet is controlled by Apple, not by your app, and the call that opens it has no callback. Because the transaction lands on the payment queue and is finished by your app, initialise your transaction handling early — the SDK described here finishes pending transactions on launch or foregrounding. The practical response pattern is therefore not to wait for a success callback, but to listen for CustomerInfo updates and react when an entitlement appears. If a subscriber redeems but has no purchase record yet, restoring purchases syncs the device receipt and unlocks the entitlement for the current app user ID.
When a redeemed code takes effect
Timing depends on subscriber status and on whether an introductory offer is also present. For new and lapsed subscribers, you choose whether both offers can be used or only the code. If both are allowed and the person is eligible, the introductory offer runs first and the code applies after it ends — for example, a free introductory week followed by a free code week. If both are not allowed, the code applies immediately and the introductory offer remains available for a later re-subscription. For existing subscribers, a code for their current subscription takes effect at the next renewal. A code for another subscription in the same group, or a higher tier, takes effect immediately or at renewal depending on upgrade or crossgrade behaviour. Codes support upgrades and crossgrades only, not downgrades. Some subscribers have reported being unable to redeem while a free trial is active; in that case, waiting until the trial ends is the suggested workaround.
Tracking redemptions and testing limits
Set up webhooks for your app and inspect transaction events: the offer_code field contains the App Store Connect reference name for a code purchase, or null when no code was used. That gives you a direct way to separate code-driven purchases from ordinary ones and to reconcile a campaign against the reference names you created. Testing has a constraint: offer codes could not be tested in sandbox at the time this workflow was documented, so testing was done in production, and a sandbox attempt could produce an expired-code error. Build your production test plan around that limitation rather than expecting sandbox redemption to work.
| Situation | What happens | Practical implication |
|---|---|---|
| New or lapsed, both offers allowed | Introductory offer first, then the code | Sequence the two free or discounted periods |
| New or lapsed, both not allowed | Code immediately; introductory offer kept for later | Do not expect both in the same subscription period |
| Existing, same subscription | Code at next renewal | Set expectations for when the price changes |
| Existing, same group or higher tier | Immediately or at renewal, per upgrade/crossgrade behaviour | Check upgrade and crossgrade settings before launch |
Timing depends on App Store Connect configuration and subscriber status.
Frequently asked questions
Which operating systems support offer code redemption?
Redemption needs iOS 14 or later, or iPadOS 14 or later. macOS is not supported for this flow.
When do generated offer codes expire?
Codes expire six months after generation unless you choose an earlier date. Deactivating a code makes it expire immediately.
Is extra platform configuration needed beyond App Store Connect?
Yes. Upload a subscription key so API requests linked to Apple offer codes can be validated. That is the only extra configuration described for this setup.
How should an app know redemption succeeded?
Listen for CustomerInfo updates. The redemption sheet has no callback, so an entitlement update is the reliable signal that access changed.
How can offer-code purchases be tracked?
Use webhooks. Transaction events include an offer_code field showing the reference name set in App Store Connect, or null when no code was used.
Can an offer code be used for a downgrade?
Offer codes work for upgrades and crossgrades, not downgrades. A lower-tier code cannot be redeemed against a higher current subscription.