Configuring iOS subscription offers
Subscription offers let you attach a custom price or a free period to a subscription that a customer already holds or has let lapse. Apple introduced them in the iOS 12.2 beta, and the setup in App Store Connect is quick. The part that takes real work is the redemption path: every offer must be signed with a subscription key before StoreKit will accept it. This guide walks the full sequence — configure, fetch, check eligibility, sign, build the discount, apply — and then looks honestly at what offers can and cannot do for a subscription business.
What a subscription offer actually is
An offer has two halves. The first is a record in App Store Connect, attached to the pricing of an auto-renewable subscription. The second is a set of StoreKit objects your app uses to present and redeem it. Both halves must agree, and the redemption half must be authorized by a signature your server produces.
Offers are restricted to people who already have an active subscription or had one that lapsed. That restriction is the single most important thing to understand before you plan a campaign around them.
Configuring the offer in App Store Connect
Offers live inside the pricing section of an in-app purchase product. Two fields matter at creation time: the Reference Name, which is only a label inside the App Store Connect interface, and the Promotional Offer Product Code, which is the value your app and server will actually use to identify the offer. Keep the product code stable and treat it as an identifier, not a description.
You then choose one of three offer types, and the type determines which durations are legal:
- Pay-up-front: one payment covers a fixed stretch. Permitted lengths are 1, 2, 3, 6, and 12 months.
- Pay-as-you-go: a reduced rate repeats for a set number of periods. Permitted lengths run from 1 to 12 months, expressed only in months.
- Free: the customer receives one free period. Permitted lengths are 3 days, 1 week, 2 weeks, 1 month, 2 months, 3 months, 6 months, and 1 year.
Save the offer in the top-right corner of the interface. After saving, the offer becomes visible to devices running iOS 12.2 or later.
Step 1: Read the offer from SKProduct
The offer you configured shows up in StoreKit as an SKProductDiscount, reached through the discounts array on SKProduct. This is the same class used for introductory offers, so it carries the price, the payment mode, the number of periods, the period duration, and an identifier. Walk the array and match on the identifier to select the offer you intend to present, then hold onto that object for the next steps.
Step 2: Confirm the customer is eligible
StoreKit will only honor an offer for someone with an active or lapsed subscription. You establish that by validating the receipt on the device, or by consulting whatever subscription record you already maintain. Once eligibility is confirmed, the SKProductDiscount gives you the price and terms to render in your paywall or win-back screen.
Step 3: Generate the signature on your server
This is the step that surprises people. The SKPaymentDiscount initializer takes five inputs, and three of them come from a signature you must produce outside the app:
- identifier — the offer's identifier.
- keyIdentifier — the identifier of the subscription key that signed the offer.
- nonce — a throwaway value generated alongside the signature.
- signature — the signature itself.
- timestamp — when the signature was created.
Create the subscription key under Users and Access in App Store Connect. Doing so triggers a one-time download of a p8 private key file. That file is required for every redemption, so store it securely and back it up; there is no second download.
Apple publishes a signing guide, but it leaves the mechanics thin. In practice you can avoid implementing the Elliptic Curve Digital Signature Algorithm by hand and use Python's ecdsa package instead. Install it with the command in the first code block below, convert the p8 key to DER with the OpenSSL command in the second block, and produce the signature with the script in the third block. The script joins the bundle ID, key ID, product ID, offer code, application username, nonce, and timestamp with a separator character, signs the result with SHA-256, and base64-encodes the output.
The script is a proof of concept. In production it belongs on your server, ideally behind logic that decides whether a given customer should receive a particular offer at all. That placement is deliberate on Apple's part: it forces offer grants to be controlled off-device. Send the signature, nonce, timestamp, and key ID back to the app.
Step 4: Build the SKPaymentDiscount
With the server values in hand, initialize SKPaymentDiscount. This is the shortest step and the easiest one to get wrong. Cast every value you receive from the server to the correct Cocoa type before passing it to the initializer; a mismatch can fail silently and leave you debugging a discount that never appears.
One behavior is worth internalizing: the initializer produces an SKPaymentDiscount no matter whether the signature is valid. A successful init tells you nothing about whether the offer will be honored. If redemption fails later, look at the signature inputs and the type casts, not at the initializer's return value.
Step 5: Apply the offer to a purchase
Redemption reuses the normal purchase flow. Create an SKMutablePayment for the product, set its applicationUsername to your app user ID, and assign the SKPaymentDiscount to the paymentDiscount property. Then submit the payment the same way you would any other purchase. The snippet in the fourth code block below shows the shape of that call.
When everything lines up, Apple presents its own confirmation sheet describing the offer. In the sandbox you will see a variant of that sheet reflecting the test offer.
What you can realistically do with offers
Apple frames the feature around retaining and winning back subscribers, and the eligibility restriction enforces that framing. Within those bounds, two patterns are worth considering.
Win-back. When a lapsed customer opens the app again, you can present a reduced price or a fresh free period. The caveat is that churn usually reflects lost usage rather than price sensitivity. Most iOS subscriptions cost under ten dollars a month, so a win-back only pays off for the subset of customers whose decision genuinely hinged on a few dollars. And because you already control which products your app displays, discounted products and subscription groups could accomplish much the same thing before offers existed.
Incentives for existing subscribers. Because an offer can attach to a live subscription, you can temporarily discount someone who is already paying. As a blanket discount that is unremarkable. As a reward it is more interesting: a free month for referring a friend, for example. Historically this was impossible without asking the customer to cancel first, since there was no programmatic way to alter a running subscription. Offers open that door.
Where offers fall short
Offers add machinery to a system that is already complicated, and the return is modest.
They do not help with price testing. The most common reason to change a price is to convert new customers, and price optimization at the top of the funnel is a well-established lever for lifetime value. Offers cannot touch that, because they exclude new subscribers. Mobile subscription businesses typically see monthly churn above 20%, which puts a premium on funnel volume and pricing rather than on rescuing individual lapsed accounts. It is doubtful that offers move churn enough to matter.
The signing requirement is heavier than the threat justifies. The stated purpose is to stop someone from tampering with the app and attaching a paymentDiscount to a product they already bought. But paying customers are not the ones attacking your app, and there are far simpler ways to extract content from a mobile app than forging a discount.
None of this means the feature is worthless. Apple investing in subscriptions at all is a good sign, and a company with Apple's market position could have ignored the area entirely. The reservation is that offers appear to have been designed without much input from people who actually earn a living from in-app subscriptions, and adoption may end up looking like introductory pricing: available, rarely used.
A short checklist before you build
Work through these in order; each one can save you a build.
- Is the target customer already subscribed or lapsed? If not, an offer cannot reach them — use a discounted product or a different subscription group instead.
- Does the offer type match the duration you want? Pay-up-front allows 1, 2, 3, 6, or 12 months; pay-as-you-go allows 1–12 months in whole months; free allows 3 days, 1 week, 2 weeks, 1, 2, 3, or 6 months, or 1 year.
- Do you have the p8 key stored somewhere durable? It downloads once.
- Is signing server-side, with a rule for which customers qualify?
- Are the server values cast to the right Cocoa types before the SKPaymentDiscount initializer runs?
- Have you tested in sandbox, where the confirmation sheet differs from production?
Frequently asked questions
Who can redeem an iOS subscription offer?
Only customers with an active subscription or a lapsed one. New subscribers are excluded, which is why offers are framed as a retention and win-back tool rather than an acquisition one.
Why does an offer need a cryptographic signature?
Apple requires it to prevent someone from modifying the app and attaching a paymentDiscount to a product they already purchased. The signature is produced with a subscription key and must be generated off-device, which is why the signing step belongs on your server.
The SKPaymentDiscount initializer succeeded but the offer was not applied. Why?
The initializer returns an SKPaymentDiscount regardless of whether the signature is valid, so a successful init is not proof of anything. Check that the server values were cast to the correct Cocoa types — a mismatch can fail silently — and verify the signature inputs and the key used to produce them.
What durations are allowed for each offer type?
Pay-up-front permits 1, 2, 3, 6, or 12 months. Pay-as-you-go permits 1 to 12 months, specified only in months. Free permits 3 days, 1 week, 2 weeks, 1 month, 2 months, 3 months, 6 months, or 1 year.
How is this different from offering a discounted product?
Functionally, a discounted product or a separate subscription group can reach the same customers, since your app already decides which products to display. Offers add the ability to alter an existing subscription without requiring a cancellation, which is what makes incentive-style rewards possible.
SKMutablePayment *payment = [SKMutablePayment paymentWithProduct:product];
payment.applicationUsername = self.appUserID;
payment.paymentDiscount = discount;
[self purchaseProduct:product withPayment:payment completion:completion];