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

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 retentionCopy link to this section

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 worksCopy link to this section

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:

1. Identifies the app, product, and subscriber
2. Checks for a configured message, promotional offer, or alternate product
3. Applies eligibility rules (storefront, subscriber age, last seen, purchase history)
4. 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 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 you can simplify the process with RevenueCatCopy 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 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 RevenueCatCopy link to this section

If your app already has early access, we can help you implement Retention Messaging today. Please contact our support team and we’ll help get you set up.   

If you’re still waiting for approval, you can still prepare your messages and localization strategy now — and go live as soon as Apple grants access. 

We have up to date documentation for the Retention Messaging API. At the moment RevenueCat supports the following messaging types:

1. Text only message: a simple message highlighting subscription features or benefits
2. Switch-plan message: suggests an alternative subscription plan that the customer could switch to, along with a short message
3. 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.

Requesting access from AppleCopy link to this section

Retention Messaging requires requesting access from Apple. Start by filling Apple’s form. Only the account holder can fill out this form. The form needs the following information:

• App Name: enter the name of your app
• Apple ID: you can find your Apple ID in App Store Connect under ‘App Information’   

• Endpoint URL: you can find this URL in your RevenueCat dashboard on the App Store app’s settings page

• On the form, make sure to select “My app currently has a subscription on the App Store.”

After submitting the form, wait for Apple’s approval. They will inform you once your access has been approved. Once Apple grants you access, please contact our support team and we’ll help get you set up.