Apple’s 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. It’s a new chance to remind users why they subscribed before they leave.
App Store Connect or the API?
Retention messages are now available directly in App Store Connect, with no server integration needed. Real-time messaging through the API remains available by request. This guide focuses on the API and RevenueCat setup; for setup using App Store Connect, see our App Store Connect setup guide.
Depending on your setup, your retention message can take one of several forms: a simple text message, a text message paired with an image, an alternative product such as a lower-priced tier, or a promotional offer like a discount. You can also combine a plan switch with a promotional offer.
If you’ve ever wanted to reach customers before they walk out the door, this API makes that possible. The catch: it also comes with tight performance limits, setup requirements, and a fair amount of backend plumbing. Read on for how it works, how it compares to setting up messages in App Store Connect, 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. When a default message exists 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 (first seen, first purchase, storefront, trial or intro offer status, and offer history)
- Returns the correct message to Apple
All of this happens in real time, within Apple’s 700ms limit. Apple prioritizes a valid real-time response; if it can’t use that response, it falls back to the message configured in App Store Connect, or to the API’s default message if there’s no App Store Connect configuration. Each message variant must be approved by Apple in advance, so you’re choosing which approved message to show when someone cancels, rather than writing new copy on the spot.
Real-time messaging vs. App Store Connect: which should you use?
Apple lets you configure retention messages in two ways: through the real-time Retention Messaging API, or directly in App Store Connect (ASC). ASC supports messages, images, and retention offers, with built-in controls for offer eligibility. The API gives you more control over which message each subscriber sees and lets you suggest an alternative plan. RevenueCat builds on that with audience targeting, A/B testing, and reporting on what happens after a save.
If you want to get a first message live without an API integration, our App Store Connect setup guide walks through that process. ASC and the Retention Messaging API can work together, so starting in ASC doesn’t mean you’ll have to abandon that setup later. You can add real-time messages for selected subscribers or products as your needs grow, while keeping your ASC configuration in place.
RevenueCat is what you need when you want different copy for trial users and paying subscribers, separate messages for people who receive an offer and those who don’t, or an experiment to compare approaches. It also gives you automatic translation and tools to manage messages across products and locales. You can start with a simple ASC message, then bring more of that work into RevenueCat when you need the extra control.
If you want targeting, plan switching, experimentation, and deeper reporting, real-time messaging is where RevenueCat can help.
Where RevenueCat goes further
Beyond handling the real-time plumbing, RevenueCat gives you tools to target, test, and measure your retention program:
- Better analytics: Track save rates and offer acceptance alongside renewals, churn, and realized revenue
- Audience targeting: Choose which subscribers see each message or offer using customer and subscription filters
- A/B testing: Experiment with different messages and offers to find what retains best, without building your own experiment assignment and reporting on top of Apple’s API
- Automatic translation: Generate translations in RevenueCat from your English (US) copy, then review and edit them together. Auto translate fills missing locales without overwriting translations you’ve already entered
- Easier configuration: Copy existing configurations and edit all locales in one screen, making it easier to manage multiple messages and products as your retention setup grows
Target messages and offers with audiences
Audience targeting is one of the main reasons to use RevenueCat’s real-time integration. You can give different groups of subscribers a relevant reason to stay and choose who should receive an offer, all from the dashboard. RevenueCat’s audience filters combine customer details such as total spending, first purchase date, or custom attributes with the details of the subscription being canceled, so you don’t have to build that targeting logic yourself.
You can target messages by free-trial or introductory offer status, storefront, and previous offer redemptions. Those subscription filters apply to the subscription the customer is canceling, so someone with multiple subscriptions can qualify for different messages on each. See the audience filters guide for the available conditions and setup steps.
Trial cancellations are a good audience to start with. Someone who is still trying the app may need a reminder of what’s included and why it’s worth returning, while a long-time subscriber may respond to a different reason to stay. Use the Is in free trial filter to give trial users their own approved message, then test that copy against another version for the same audience.
You can also write separate messages for subscribers who receive an offer and those who don’t, so the copy makes sense in either case. For example, you could reserve a discount for subscribers who haven’t redeemed a promotional offer in the last 30 days. Conditions within a group use AND, so all must match; separate groups use OR, so matching one group is enough. Start with a simple audience and check that your sandbox subscriber matches the rules you intended.
If several messages could apply to the same subscriber, check their order as well as their rules. Outside an experiment, RevenueCat serves the eligible real-time message that was created first, falling back to the default when none matches. Keeping those rules easy to follow makes it easier to understand why a subscriber saw a particular message.
Test messages and offers with Experiments
Once you’ve chosen who should see a message, you can test what works best for that audience. You might compare a clearer reminder of subscription benefits with your current copy, or test whether adding a discount saves enough subscribers to justify the lower price. Start with one specific hypothesis and change one meaningful element at a time.
From Lifecycle → Retention, select New experiment for your app, give it a name, and choose the approved messages you want to compare. Set the percentage of eligible subscribers to include in the test. Save rate is the primary metric, with realized LTV per customer and churned subscribers as secondary metrics, so you can follow both the immediate response and what happens afterward.
The messages you compare need compatible products, locales, and audience rules. Check the retention messaging experiments guide for the full requirements before starting your test. Experiments is available to Pro and Enterprise customers.
Subscribers who aren’t included in the experiment still receive whichever message your normal retention configuration selects. They aren’t a control group that sees no message. The experiment tells you how your messages and offers compare with each other; it doesn’t measure the effect of retention messaging against a cancellation screen with no message at all.
Measure what happens after the save
A subscriber deciding not to cancel is a useful first signal, but you also need to know whether they renew and how much revenue they bring in afterward. Review save rate alongside offer acceptance, the share of subscribers still active and set to renew, churn, and realized LTV per customer. Give those results time to develop: realized LTV is the revenue observed so far, not a prediction of what a subscriber will eventually spend.
A discount could save more subscriptions at the cancellation screen while bringing in less revenue afterward. Before choosing a winner, look at both outcomes and decide which matters most for your test. A higher immediate save rate alone doesn’t tell you whether the offer is worth keeping.
Our Apple retention messaging benchmarks can help you put your results in context and decide what to test next. They describe what we’ve observed across apps, so don’t treat a save rate as proof that every subscriber counted as saved would otherwise have canceled. Apple and RevenueCat also use different reporting definitions; check those definitions before comparing their totals.
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 and approved for each product and locale
With a custom API integration, the orchestration, performance, and data management are your responsibility. It’s not overly complex, but it is 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 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 can configure all your retention campaigns under Lifecycle → Retention in the RevenueCat dashboard. Define messages and promotional offers, then tailor campaigns to specific groups — by storefront, intro offer status, or how long someone has been a subscriber — without touching backend code. Your cancellation messages and offers live alongside the rest of your subscriber lifecycle tools.
Getting started with Retention Messaging API in RevenueCat
To use the real-time Retention Messaging API, you’ll need to request access from Apple. Our step-by-step guide in the RevenueCat docs covers the prerequisites, and the video below walks through the dashboard setup.
While you’re waiting for approval, you can prepare your messages and localization strategy. You’ll also need to pass Apple’s performance test in sandbox before using real-time messaging in production. RevenueCat lets you start and track that test from the dashboard; the steps below cover the setup from there.
1. Request API access from Apple
Your Apple Developer account holder needs to request API access from Apple, using the endpoint URL and app information described in RevenueCat’s setup instructions. Creating a message directly in App Store Connect doesn’t automatically grant access to real-time messaging, so you’ll need this approval even if you already use Apple’s no-code setup.
2. Connect sandbox and run the performance test
In your RevenueCat project, go to Lifecycle → Retention, find your App Store app, and connect the sandbox real-time URL. Then run Apple’s performance test using an active sandbox or TestFlight purchase. The test can take up to an hour, so choose a subscription that will remain active throughout; a purchase made with a local StoreKit Configuration file won’t work.
3. Create a default message
Create a default message, select the products it covers, and add your title and body text for each locale, along with an image if you’re using one. This message is the fallback when none of your real-time messages applies, so write copy that makes sense for everyone on those products. You can use Auto translate to fill in other locales, then review the translations before submitting them.
4. Create your real-time messages
Create a real-time message, give it a reference name, and choose the active subscription product. You can add an alternate plan, a promotional offer, or both; with neither selected, you can serve a text message with an optional image. Promotional offers are configured in App Store Connect, then associated with the message and active product in RevenueCat.
Add your audience rules and localized copy to complete the message. The example below shows an active message with an audience condition and a promotional offer for a monthly subscription.
5. Test the flow and configure production
Test the cancellation flow to check that the intended message appears for each subscription and audience. Verify the copy, locales, offers, and fallback behavior, then configure the production URL after passing the performance test. Sandbox and production use separate configurations, so check your production messages and Apple approval statuses before going live.
Also configure App Store Server Notifications if you haven’t already. Messages can be delivered without them, but RevenueCat needs those notifications to report accurate retention charts.
RevenueCat supports the following message types:
- Text-based message: a simple message highlighting subscription features or benefits
- Text-based message with an image: an image alongside a message highlighting subscription features or benefits (3840 × 2160 PNG, no transparency)
- 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
- Switch-plan message with a promotional offer: suggests an alternative subscription plan and includes a promotional offer for that plan
Retention messages are visible on devices running iOS 15.1 or later, iPadOS 15.1 or later, visionOS 1 or later, or macOS 14 or later.
These messages are shown to users after they tap Cancel Subscription on the subscription details page. On the Confirm Cancellation screen, users can 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, check out our Retention Messaging API documentation.