Greetings, traveler!
On November 4, 2026, Apple announced that Retention Messaging is now available for auto-renewable subscriptions. First introduced at WWDC26, the feature allows developers to display custom messages and subscription offers when users attempt to cancel through the App Store.
Until now, developers had limited opportunities to reach subscribers during Apple’s cancellation process. They could present offers inside their apps or use Win-Back Offers to encourage former subscribers to return. Retention Messaging makes it possible to reach users before they complete a cancellation.
Apple provides two ways to configure the feature: directly through App Store Connect or through a server-side API that supports personalized messages and offers.
How Retention Messaging Works
When a subscriber attempts to cancel an active subscription, Apple’s cancellation confirmation screen can display a message from the developer.
Three presentation formats are available:
- Text only: A title and description explaining the benefits of keeping the subscription or announcing upcoming content.
- Text and image: A message accompanied by an image selected from the App Store Connect Asset Library.
- Text and offer: A message with a discounted subscription or a free subscription period.
Text is required for every retention message. Images and offers are optional.
If a message includes an image and one or more offers, eligible subscribers see an offer instead of the image. Those who don’t qualify can still see the original text and image.
The message appears within Apple’s subscription management interface. Users can accept an offer, keep their existing subscription, or proceed with cancellation without opening the app.
Configuring Retention Messages in App Store Connect
The simplest implementation requires no additional backend or changes to the application’s UI. Open your app in App Store Connect and navigate to:
Monetization → Subscriptions → Retention Messaging
Select Get Started to create a message.
The setup involves entering an internal reference name, writing the message, adding localizations, and associating it with one or more subscriptions. You can optionally select an image and configure retention offers before submitting the message for App Review.
Apple allows up to 10 retention messages per app. A message can be shared across multiple subscriptions, but each subscription can have only one assigned retention message at a time.
Messages can also be created and managed through the App Store Connect API.
After approval, developers can update the message text or image without releasing a new app version. App Store Connect creates a new draft while the previously approved message remains available to subscribers. Once the replacement passes review, it becomes the published version.
There are restrictions on message content. Apple doesn’t allow pricing, discounts, or promotional offers to be mentioned in the message’s title or body. Phrases such as “50% off,” “$9.99,” or “one month free” will result in rejection.
The restriction exists because all subscribers see the same message text, including those who aren’t eligible for an associated offer. App Store displays the actual offer terms separately.
You can describe features that become unavailable after a subscription ends, provided the statements are accurate. Claims intended to pressure subscribers into staying or promising unverifiable outcomes should be avoided.
Retention Offers and Subscriber Eligibility
Alongside retention messages, Apple introduced a new subscription offer type called a Retention Offer.
Retention Offers are configured in App Store Connect and associated with individual subscriptions. They can provide a discounted price or a free subscription period.
Each subscription billing plan type supports up to 10 retention offers, all of which can be associated with a single message.
When configuring an offer, developers specify its pricing, duration, availability, and eligibility conditions.
Two eligibility settings are particularly useful:
- Paid Subscription Duration: The minimum amount of time a subscriber must have maintained a paid subscription before qualifying.
- Wait Between Offers: The period a subscriber must wait before redeeming the same retention offer again.
Wait Between Offers applies independently to each offer. A subscriber who has already redeemed one offer may still qualify for another without waiting.
If several offers are available to the same subscriber, App Store automatically selects which one to display.
Retention Offers support the familiar Pay as you go, Pay up front, and Free pricing structures.
Unlike Win-Back Offers, which target subscribers after their subscriptions have ended, Retention Offers are presented during the cancellation process.
Real-Time Retention Messaging API
Developers who need more control can use the Retention Messaging API.
The primary difference is how the message is selected. With App Store Connect, Apple selects the configured message and any eligible offer. With the real-time API, the developer’s server makes that decision for each subscriber.
When a customer views subscription details where cancellation is possible, App Store sends a server-to-server HTTP request to the developer’s configured endpoint. The selected message is displayed when the customer proceeds to the cancellation confirmation screen.
The request contains a signed payload with information including:
originalTransactionIdappAppleIdproductIduserLocalerequestIdentifierenvironmentsignedDate
The originalTransactionId can be used to identify the subscriber’s history in the developer’s backend.
For example, a server could examine how long someone has been subscribed and select a message appropriate for that customer.
The API supports three standard response types.
Message
Displays a previously configured message, with or without an image.
Promotional offer
Displays a message alongside a promotional subscription offer.
Alternate product
Offers another subscription within the same subscription group, such as switching from a monthly plan to an annual plan.
Here is an example of an alternateProduct response from Apple’s WWDC26 presentation:
{
"alternateProduct": {
"messageIdentifier": "ed7f25fc-5741-46a3-8502-062e0fb8afd0",
"productId": "Yoga_summer_2026_annual"
}
}The response references an approved message and identifies the subscription product to offer.
For a promotional offer, the response uses the promotionalOffer object. Apple supports both V1 and V2 promotional offer signatures, with promotionalOfferSignatureV2 recommended for new implementations.
The ability to recommend another subscription plan is one reason to consider the real-time API. This option isn’t available through the standard App Store Connect configuration.
Retention Offers vs. Promotional Offers
Although both implementations can present discounted subscriptions during cancellation, they use different offer mechanisms.
Retention Offers belong to the App Store Connect implementation. Apple evaluates the eligibility rules configured for the subscription and selects an appropriate offer.
Promotional Offers are used by the real-time API. The developer’s server selects the offer and provides the required signature.
This distinction affects how much control the developer has over offer selection and eligibility.
For a straightforward discount intended for established subscribers, a Retention Offer may be sufficient. Applications with more complex subscriber segmentation can use Promotional Offers through the real-time API.
The real-time implementation also requires additional infrastructure. The server must verify the JSON Web Signature (JWS) on incoming requests and return a valid RealtimeResponseBody with HTTP status 200.
Apple imposes a strict response-time limit of 700 milliseconds in production. Requests exceeding that limit fail.
Before configuring a production endpoint, developers must pass a performance test in the Sandbox environment. If the server fails or returns an invalid response, App Store first attempts to display the retention message configured in App Store Connect, including an eligible offer. If that isn’t available, it falls back to the default message configured through the Retention Messaging API.
For this reason, Apple recommends configuring App Store Connect retention messages even when using the real-time API. Access to real-time Retention Messaging is available by request.
Changes to StoreKit and Subscription Transactions
Retention Offers introduce a new value in signed transaction and renewal information:
offerType = 5
This identifies a redeemed Retention Offer.
Apple also includes the associated offer information through existing fields such as:
offerIdentifierofferDiscountTypeofferPeriod
For example, a transaction containing a redeemed free retention offer may include:
{
"offerType": 5,
"offerIdentifier": "Yoga_2026_cancel_free_3m",
"offerDiscountType": "FREE_TRIAL",
"offerPeriod": "P3M"
}These fields are taken from the transaction example Apple presented at WWDC26.
The new value identifies Retention Offers specifically. Developers shouldn’t assume that every offer presented through the Retention Messaging API uses offerType = 5, since the real-time API can also present Promotional Offers.
If your application or backend parses signed transactions and renewal information, check whether its offer-handling logic supports the new value. This is particularly relevant when offer types are represented by a fixed enumeration or used to classify subscription revenue.
The existing subscription entitlement model remains unchanged. Applications should continue to determine access from the user’s verified subscription transactions and current subscription status.
Testing Retention Messaging
Retention messages can be tested in Sandbox before publication. App Store Connect provides a preview that allows developers to inspect different subscriptions and offers, including the version shown to subscribers who aren’t eligible for any offer.
Sandbox testers can also see draft messages that haven’t yet passed App Review. A useful test should cover:
- Canceling a subscription with a text-only message.
- Confirming that eligible subscribers see the configured offer.
- Checking that ineligible subscribers see the fallback text and image.
- Verifying the
offerType, identifier, and discount fields after a Retention Offer is redeemed. - For real-time implementations, checking server responses, signature validation, and fallback behavior.
The real-time API also includes Sandbox performance-testing endpoints. Passing the required test is necessary before enabling the production endpoint.
Measuring Retention Performance
At WWDC26, Apple shared early results from subscriptions using Retention Messaging. According to Apple, subscriptions adopting the feature experienced an average save rate increase of 1.4 percentage points, equivalent to an 82% relative increase.
Messages containing promotional offers showed a larger observed increase of 5.5 percentage points, equivalent to a 223% relative increase.
Apple noted that results varied across developers. Save rate measures the percentage of subscribers who keep their subscriptions after reaching the cancellation confirmation page.
There is an important detail in how Apple records this metric. The Don’t cancel category includes users who explicitly choose not to cancel, as well as users who dismiss the cancellation sheet without taking any action.
Consequently, an increase in save rate doesn’t necessarily translate into long-term retention. A subscriber might dismiss the cancellation screen and cancel later. Someone accepting a discounted offer may also generate less revenue during the promotional period.
Apple provides an App Store Retention Messaging analytics report to help developers measure the results.
The report includes page views, completed cancellations, saved subscriptions, redeemed offers, and subscription plan changes. Results can be broken down by subscription tier, message type, territory, device, and platform version.
The data is updated daily, with completeness expected within four days. you can use the report to understand how subscribers respond to different messages, then compare those results with subsequent renewals and actual subscription revenue.
Which Implementation Should You Choose?
For an application with a relatively simple subscription model, you can start with App Store Connect. It supports custom messages, images, and discounts without additional backend infrastructure. Messages can be updated independently of app releases, and Apple handles offer eligibility and selection.
The real-time API makes more sense when an application already maintains subscriber histories on a backend, requires more sophisticated eligibility decisions, or wants to recommend alternative subscription plans.
Its flexibility comes with additional implementation and maintenance costs, particularly around signed requests, promotional offers, server availability, and response times.
A reasonable starting point is a simple message explaining what subscribers will lose when their subscription ends. Once enough data is available, developers can experiment with offers and evaluate whether they improve renewals and revenue.
Retention Messaging gives developers another way to communicate with subscribers during a part of the subscription lifecycle that was previously controlled almost entirely by Apple. For existing subscription-based apps, the App Store Connect implementation is straightforward enough to be worth testing.