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.
Why Retention Messaging API matters for subscription retention
When a user opens the Apple subscription settings and chooses to cancel, Apple contacts a backend endpoint fApple’s Retention Messaging API opens a new avenue to communicate with subscribers wanting to cancel. Instead of losing users at that critical moment, you can show an incentive, reminder, or discount directly within the native iOS subscription management screen.
RevenueCat makes this new channel accessible to every app, no custom infrastructure needed. You can simply configure, test, and monitor your retention messages in the same dashboard you already use for Customer Center, Paywalls, and other features.
We will also support new analytics that will help you track how many intended cancellations convert into redemptions, plan changes, or completed cancellations.
Ultimately, the result is another tool in your retention toolkit, integrated right into the RevenueCat ecosystem, and designed to help you keep more subscribers engaged and active.
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: