Understanding Apple’s Retention Messaging API (and how RevenueCat can help you with it)

Earlier this year, Apple quietly launched a new API that gives apps a powerful way to keep subscribers from churning: the Retention Messaging API.

It 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.

So 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 how it works, why it matters, and how RevenueCat can take care of the painful parts for you.

What happens when a user taps ‘Cancel’Copy link to this section

When a user opens the Apple subscription settings and chooses to cancel, Apple contacts a backend endpoint for your app. The request includes information about the transaction, the product being canceled, and the app ID. It’s worth noting, however, that Apple only contacts your backend if you have a default retention message configured for that product and locale.

Provided you have that message configured correctly, your server has less than 700 milliseconds (0.7 of a second) to respond with the alternate offer or message.

Luckily, RevenueCat’s backend handles this sequence automatically:

• It identifies the app and transaction, then looks up the subscriber
• It checks whether there is a configured alternate offer or product
• It applies any eligibility criteria, such as storefront, last seen date, or purchase history
• If the user qualifies, it sends Apple the correct offer to display

That entire exchange happens in real time, within Apple’s strict performance of 0.7s. It’s an extremely tight window to catch users from slipping through the cracks — all the more reason to ensure everything is set up correctly.

What implementing the API yourself looks likeCopy link to this section

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 RevenueCat simplifies the processCopy link to this section

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.

Here’s what we can handle 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’ll soon be 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.

Reliability, performance, and monitoring of your Retention MessagingCopy link to this section

RevenueCat tracks the latency of every real-time request to ensure responses stay well below Apple’s 700ms limit. We log every request, and response, to allow debugging and visibility into campaign performance.

Localization is fully managed, too: our automated translation pipeline ensures your messages stay consistent across languages and storefronts, powered by machine learning models fine-tuned for in-app communication.

In other words, you get Apple’s new retention capability with enterprise-grade reliability — and no backend work required on your side.

Why this matters for subscription retentionCopy link to this section

Apple’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 settings 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’re also planning 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.

Getting started with Apple’s Retention Messaging APICopy link to this section

Access to Apple’s Retention Messaging API is currently invite-only through Apple’s early access program. RevenueCat is already working closely with apps and developers who have been accepted into this early-access cohort to help them implement and test retention messages in production. We’d love to work with you, too — you can learn more here with our documentation.