Skip to content
AppDues
Log in
Contact salesSign up

Signing iOS subscription offers

A promotional subscription offer lets you give a specific price or free period to a customer who has subscribed before. The hard part is not the discount itself; it is the chain of trust around it. App Store Connect holds the offer definition, a subscription key proves your signing backend is allowed to sign it, and your app must decide who sees the offer before Apple's purchase sheet appears. This guide follows that chain end to end using a Swift example that targets recently cancelled subscribers.

Configure the offer in App Store Connect

Offers live under an existing subscription product rather than as a separate product. Open the product, find Subscription Prices, and use the “+” control to choose Create Promotional Offer. Two fields matter at this stage. The Reference Name is internal and exists only to help you recognise the offer later. The Promotional Offer Product Code is the identifier your app uses to activate that specific offer, so it is the value you will match against in code. You do not have to surface the product code to customers, though nothing prevents you from doing so if your flow needs it.

The next screen asks which kind of offer you want. Three shapes are available, and their duration rules differ:

  • Pay-up-front: one payment covers a fixed stretch of time, for example $0.99 for 3 months. Durations are limited to 1, 2, 3, 6 or 12 months.
  • Pay-as-you-go: a reduced rate is charged each period for a set number of periods, for example $0.99 per month for 3 months. Durations run from 1 to 12 months and must be expressed in months.
  • Free: the customer receives one free period, similar to a trial. Allowed durations are 3 days, 1 week, 2 weeks, 1 month, 2 months, 3 months, 6 months and 1 year.

Save the offer in the upper right before leaving the screen. The worked example in this guide uses a pay-up-front offer aimed at lapsed premium users: three months of access for $0.99, in the hope that they remain subscribed once the offer period ends.

Generate and download the subscription key

A subscription key is what lets your backend authenticate and validate a subscription request with Apple. Keys are created in the Users and Access area of App Store Connect, and a single key can serve every offer you run, so you do not need a new key per promotion.

Use Generate Subscription Key and give it a name. The new key appears under Active Keys, and the download is a one-time opportunity, so treat the file as something you cannot re-fetch later. Choose Download API Key and store it somewhere safe; the next step consumes it. With the offer defined and the key in hand, the App Store Connect side is complete.

Upload the subscription key to your signing backend

The key does not belong in your app binary. It goes to the backend that will sign offers on your behalf, where it is used for server-side authentication and validation of the offers. Open your app's Settings in that backend's dashboard and upload the Subscription Key .p8 file you downloaded from App Store Connect. If you have not created an app record yet, sign up and add a new app first, then return to Settings. Once the file is uploaded, no further configuration is needed for signing.

The same steps apply to any backend that accepts an App Store Connect subscription key.

Decide which users should see the offer

Eligibility is narrower than it first appears. Only customers who have had an active subscription in your app at some point, including people who are subscribed right now, qualify for a subscription offer. Apple does not expose an eligibility flag the way you might hope, so your app has to make its own judgement, much as it does for trial eligibility.

Apple still enforces the rule at payment time. If an ineligible customer reaches the purchase sheet, they are shown the regular product rather than the offer, no matter what your app tried to present. That is the failure mode worth designing around: a customer told to expect a deal who then sees full price. The distinction is worth keeping straight, because it is a gating problem in your app, not a signing failure.

A practical checklist before you show anything:

  • Confirm the customer has a subscription history in your app.
  • Apply your own business rule on top, such as a minimum gap since expiry.
  • Record that the offer was shown so it is not repeated indefinitely.
  • Only present the offer when all of the above pass.

The example targets people whose paid subscription expired more than seven days ago, on the theory that a deal may bring them back. The base project is the SwiftExample app from the Purchases iOS repository, a small app where subscribers see happy cat emojis and non-subscribers see sad ones. CatsViewController.swift is where the offer decision is made.

Write the eligibility check

The check is a single function that returns a boolean. It looks at the expiration date for the pro_cat entitlement, adds seven days' worth of seconds, and compares the result with the current date. It also reads a UserDefaults flag named has_seen_promo_cat_discount, so anyone who has already been shown the offer is treated as ineligible. Both conditions must hold before the function returns true. The complete function is supplied as an exact code module alongside this page.

Wire the check into the view

The check is appended to the existing function that configures the cat content. Inside the branch where the pro_cat entitlement is not active, the code asks whether the offer should be shown, and if so schedules the upsell after a two-second delay to soften the transition. The whole block is wrapped in an availability check for iOS 12.2 and later, since the offer APIs require it. The exact wiring is supplied as a code module.

Sign the offer and let the customer redeem it

With the offer configured and the audience chosen, the remaining work is a single function, showPromoUpsell(), that runs in three stages.

First, fetch the product and its discount. The code pulls the active product for the monthly_cats offering from the pro_cat entitlement, then finds the discount whose identifier is promo_cat. Guard statements catch a mistyped key name at either point, which is the most common way this step fails.

Second, obtain the signed discount. The Purchases SDK's paymentDiscount method takes the SKProduct and SKProductDiscount and returns an SKPaymentDiscount. Behind that call, the signing backend signs the offer using the subscription key uploaded earlier, which is why the key never needs to ship inside the app.

Third, present and purchase. A helper shows a UIAlertController offering the deal, and if the customer accepts, makePurchase is called with both the product and the signed discount. Apple then displays its standard confirmation sheet describing the promotional terms. When the transaction completes, the view is reconfigured so premium content appears. The helper also sets the has_seen_promo_cat_discount flag at the moment the alert is presented, which is what stops the offer from reappearing.

The full function, the helper, and the staged excerpts are supplied as exact code modules. Read them in order: the product and discount lookup, the paymentDiscount call, the alert and makePurchase step, and finally the combined function.

Field and control map

The table below pairs each value in the flow with where it is set and what consumes it, which is useful when a purchase sheet shows the wrong price.

ValueSet inUsed by
Reference NameApp Store Connect offer screenYour own records only
Promotional Offer Product CodeApp Store Connect offer screenMatched in app code to select the discount
Subscription key (.p8)App Store Connect, Users and AccessUploaded to the backend that signs offers
Offer type and durationApp Store Connect offer screenDetermines the terms Apple displays
Entitlement expiration datePurchase dataThe eligibility check
has_seen_promo_cat_discountUserDefaultsSuppresses repeat presentation
SKProductDiscountProduct lookupInput to paymentDiscount
SKPaymentDiscountpaymentDiscount resultInput to makePurchase

Frequently asked questions

Why did an ineligible customer see the regular price instead of the offer?

Apple enforces offer eligibility at payment time. If the customer does not qualify, the purchase sheet shows the normal product regardless of what your app presented. Your own eligibility check exists to avoid that mismatch, not to override Apple's decision.

Do I need a separate subscription key for each offer?

No. One subscription key can be used across all of your offers. It is created in Users and Access in App Store Connect and uploaded once to the backend that signs offers.

Can I download the subscription key again later?

The download is available once, when the key is generated. Store the file securely at that point, because you will not be offered a second download.

Which iOS version is required?

The offer flow in this example is gated behind iOS 12.2 and later, using an availability check around the upsell code.

What durations does each offer type allow?

Pay-up-front allows 1, 2, 3, 6 or 12 months. Pay-as-you-go allows 1 to 12 months, specified in months only. Free allows 3 days, 1 week, 2 weeks, 1 month, 2 months, 3 months, 6 months or 1 year.