Apple’s new Retention Messaging API lets apps reach subscribers at the exact moment they choose to cancel, showing a message, incentive, or discount directly within the iOS subscription settings screen. This creates a new opportunity to re-engage users who might otherwise leave.
Depending on your setup, your message can take one of three forms: a simple message (optionally with an image), an alternative product such as a lower-priced tier, or a promotional offer like a discount or extended trial.
If you’ve ever wanted to reach customers before they walk out the door, this API finally makes that possible. However, it also comes with tight performance limits, tricky setup requirements, and a fair amount of backend plumbing.
Read on for why retention messaging matters, how it works, and how RevenueCat can take care of the painful parts for you.
How Apple’s Retention Messaging API works
When a user enters the iOS subscription management screen and taps Cancel, Apple checks whether you’ve configured a default retention message for that specific product and locale. If you have, Apple calls your backend with the subscriber’s transaction information and waits for your response. If a default message is configured for that product and locale, Apple gives your server under 700ms to return the message, alternate product, or promotional offer.
RevenueCat handles this entire real-time sequence for you:
- Identifies the app, product, and subscriber
- Checks for a configured message, promotional offer, or alternate product
- Applies eligibility rules (storefront, subscriber age, last seen, purchase history)
- Returns the correct message to Apple
All of this happens in real time, well within Apple’s 700ms limit.
What implementing the API yourself looks like
Building an Apple Retention Messaging integration from scratch requires more than just calling the API. Developers have to:
- Configure default messages for every product and locale manually
- Maintain an always-on backend that can process Apple’s requests in under 0.7s and handle promo offer signing
- Keep track of which messages are configured for each locale, since Apple doesn’t store this information
Apple only provides the raw API endpoints, leaving the orchestration, performance, and data management entirely up to the developer. It’s not overly complex, but it’s undeniably cumbersome and time-consuming to test, localize, and iterate.
How you can simplify the process with RevenueCat
If you don’t fancy doing the manual build and maintenance, RevenueCat can manage every part of Apple’s Retention Messaging setup and response flow for you:
- Uploading messages and configuring default text for each locale
- Generating AI-backed translations automatically, so your retention messages are localized without manual work
- Monitoring message status through the Apple API
- Responding to Apple’s real-time requests with latency safely below 0.7s
You’re able to configure all your retention campaigns directly in the RevenueCat dashboard. Define messages, promotional offers, and tailor campaigns to specific user cohorts — for example, by storefront, trial status, or how long someone has been a subscriber — all without touching backend code.
The retention section in the dashboard sits alongside your Customer Center configuration, so you can manage both user-facing offers and cancellation retention messages in one place.
Getting started with Retention Messaging API in RevenueCat
Retention Messaging currently requires requesting access from Apple. You can do this quickly following our step-by-step guide in the RevenueCat docs.
Access update
In April 2026, Apple has expanded access to the Retention Messaging API, with broader availability rolling out in the coming weeks. If you've been waiting on the sidelines, now's the time to get your messages and localization set up in RevenueCat so you can ship the moment access lands.
Some developers are alos seeing long wait times for production message approvals. This seems to be a delay on Apple's side and not an issue with any one app.
While you’re waiting for approval, you can still prepare your messages and localization strategy now — and go live as soon as Apple grants you access.
At the moment RevenueCat supports the following messaging types:
- Text only message: a simple message highlighting subscription features or benefits
- Switch-plan message: suggests an alternative subscription plan that the customer could switch to, along with a short message
- Promotional-offer message: offers a discounted price for continuing the subscription, either at the same tier or a different tier of service, alongside a short message
Retention Message API supports messages with images, but RevenueCat will initially focus on text-only, switch-plan, and promotional-offer messages. Support for image-based messages may be added in the future.
These messages are shown to users after they tap ‘Cancel Subscription’ on the subscription details page. On the Confirm Cancellation screen, users can either complete the cancellation, tap ‘Don’t Cancel’, or, depending on the message, redeem an offer or switch to a suggested subscription.
For all of the up-to-date details on implementing these in your app using RevenueCat, checkout out our Retention Messaging API documentation.