Apple Retention Messaging API: Message Before Cancel

The Retention Messaging API is a server-to-server Apple service that shows your message to a subscriber right when they tap Cancel Subscription. The message appears on a confirmation page, before the cancellation goes through. It can remind them of your subscription's value, offer another plan or a promotional offer, but the cancel button is always still there. The API has been in preview since July 2025, on request, and Apple announced a simpler version inside App Store Connect for fall 2026.

This guide explains what the API shows, how long it's been around, who can use it, its requirements and how to set it up. Everything comes from Apple's documentation and the WWDC26 session dedicated to it, reviewed on November 3, 2026.

I sell subscriptions in my iOS apps: Solys, a social media blocker, TradaZen, a trading simulator, Nolera, an AI outfit try-on app, and Vigie. I requested API access for all four on October 25, 2026, and prepared their messages in every language they support. As of October 28, Apple's approval hadn't come in yet: so this guide describes the rules and my preparation, not results yet.

What the Retention Messaging API does

According to Apple's documentation, the API lets you choose the message the system displays when a customer views a subscription's detail page and may be about to cancel. You prepare your messages in advance, for each product and each language.

The flow is always the same:

1. The subscriber opens their subscription, for example in Apple Account, Subscriptions, or from the App Store.
2. They tap Cancel Subscription.
3. The system shows a confirmation page (Confirm Cancellation), with your message.
4. They can cancel anyway, keep their subscription, or accept what your message offers.

The message shows on iOS 15.1 and iPadOS 15.1 or later, on visionOS 1 and on macOS 14 or later.

Since when, and for whom

Date	What changes, according to Apple
Jul 16, 2025	Version 1.0: first preview of the API
Dec 9, 2025	Server performance test for real time
Mar 31, 2026	Bullet points in messages, setting the real-time endpoint via the API
Apr 27, 2026	Support for monthly subscriptions with a 12-month commitment
June 2026	WWDC26: a module in App Store Connect is announced

The dates come from the API changelog, except the last one, which comes from the WWDC26 session. The API is still a preview: the documentation links to an access request form, which requires signing in to your developer account.

At WWDC26, the session Explore Retention Messaging in App Store Connect presents a no-code module inside App Store Connect. Apple says it's "open to everyone." The real-time version, though, stays on request. The App Store what's new page announces the module for "this fall." As of November 3, 2026, App Store Connect Help still has no page about it, and the module didn't show up in my account on October 28.

The API is for apps that sell an auto-renewable subscription. It's not just for big publishers: RevenueCat notes in its study of 22 million messages that small apps can request access too.

The 4 message types

Type	What the subscriber sees	Default message	Real time
Text	A title, body text, up to five bullet points	Yes	Yes
Text with image	The same, with an image	Yes	Yes
Plan switch	Text and another subscription from the same group	No	Yes
Promotional offer	Text and an offer to continue at a reduced price	No	Yes

According to the page on setting up messages, a default message can only be text, with or without an image. With the API, offering a discount or another plan requires responding in real time. The module announced in App Store Connect, on the other hand, will offer a message with an offer, no server needed.

The promotional offer is the one you create in App Store Connect. According to the help page on promotional offers, it targets current and former subscribers. In a retention message, your server signs it, according to the page on setting up messages. The plan switch offers a subscription from the same group. If you're new to these offers, read my guide on offer codes and promotional offers first.

What you can show: the exact limits

Element	Apple's limit
Title	66 characters max
Body text	144 characters max
Bullet points	5 max
Full-width image	PNG without transparency, 3,840 px wide, 160 to 2,160 tall
Bullet image	1,024 × 1,024 px
Images per app	2,000 max

The lengths come from the description of the upload message request body, and the formats from the page on uploading an image. Apple also asks for images that work equally well in light mode and dark mode.

Every message and every image is reviewed by Apple. Their state goes from PENDING to APPROVED, and the system only displays what's approved. In sandbox, approval is automatic. The documentation sets a clear content rule: don't send anything misleading or inaccurate.

The requirements

• A default message for each product, in each language. Without it, nothing shows in that language. It's also the fallback if your server doesn't respond.
• Approved messages and images before anything goes live.
• For real time, a fast server. The page on setting up the real-time endpoint requires a valid SSL certificate, TLS 1.2 and a response in under 700 ms in production. Beyond that, the request fails and the default message is shown.
• A passed performance test in sandbox, before you register your production endpoint.
• An app check. Every request from Apple includes the app identifier, appAppleId. If it doesn't match yours, Apple asks you not to respond.

The real-time request gives you the original transaction ID, the product and the device language. It's up to you to pick the message, based on your own rules.

Setting up Retention Messaging: three paths

Path	For whom	What you need
App Store Connect module	Everyone, once it ships	No code; text, image or offer
API, with your server	Those who have a back end	Apple access, HTTPS endpoint, performance test
API, through RevenueCat	Apps already on RevenueCat	Apple access, settings in the dashboard

When several setups coexist, Apple explains the order in the WWDC26 session: the real-time response first. If it's missing or malformed, the App Store Connect setting. If that doesn't exist, the default message configured through the API.

With your own server

1. Request access with Apple's form.
2. Upload your images, then your messages, with a title and body text for each.
3. Wait for approval, then set a default message for each subscription and each language.
4. For real time, create the Get Retention Message endpoint on your server and register it in sandbox.
5. Run the performance test, in sandbox, with a test transaction.
6. Once the test passes, register your production endpoint.

With RevenueCat

That's the path I picked: no server to write, and my apps already go through RevenueCat, as I explain in RevenueCat and iOS in-app subscriptions. According to RevenueCat's documentation:

1. In Apple's form, the endpoint to give is the one RevenueCat shows in your App Store app settings.
2. Once approved, open Lifecycle, then Retention, and connect the sandbox endpoint.
3. Run the performance test with an active sandbox or TestFlight subscription. It can take up to an hour.
4. Create a default message first, language by language.
5. Then add real-time messages, with rules. One of them, "Is in free trial," targets people on a free trial.
6. Move to production: sandbox settings don't carry over, you have to recreate the messages.

Writing a message that retains without tricking

The text is fixed and reviewed by Apple before it's shown. So it can't talk about the specific person reading it, or the day they read it. Here's the default message I prepared for TradaZen, translated from the French version:

Title (59 characters):
You wanted to learn trading, and now you're going in blind?

Body (130 characters):
Without practice, your real money pays for every mistake. Here, they cost nothing. Your streak, your league and your lessons stop.

The rules I set for my four apps:

• The title points the person back to their goal, as a question. It doesn't shame them.
• The text says exactly what stops. I write that access "gets locked" when the data stays, never that it will be "deleted."
• No time words like "tomorrow" or "today": the same text shows at any point in the period.
• No promise of earnings, no fake urgency. A first title that promised to change your life through trading was dropped before submission. Guideline 5.6 forbids any manipulative practice, and TradaZen's paywall was already rejected on those grounds, as I explain in guideline 5.6 and the paywall.
• Each language gets its own text, using the translated app's vocabulary, and counted down to the character.

For TradaZen, I'm also planning a real-time message for people on a trial of the annual subscription. It will offer a cheaper annual plan from the same group, because my numbers show these people use the app as much as paying users: it's the price they're saying no to. This setup is waiting on Apple's approval.

What to expect

Don't count on a miracle. Apple calls the save rate the share of subscribers who keep their subscription once they reach the confirmation page. In the WWDC26 session, Apple says subscriptions that adopted Retention Messaging gain 1.4 points of that rate on average. Messages with a promotional offer show the best observed gain, 5.5 points, and results vary from one developer to another. For its part, RevenueCat's study finds that subscribers accept only about 1.1% of promotional offers and 0.6% of plan switches.

So the message doesn't replace the work upstream. A free trial canceled within a minute is won or lost on the paywall and the first sessions: the causes and fixes are in my guide on canceled free trials, and setting up the trial is covered in the introductory offer guide.

Prepare your subscription before the message

The iOS & Android Kit starts from my apps' Starter Code: onboarding, paywall and subscriptions are already coded, and the four-step path takes you all the way to the App Store, at your own pace. The whole chain, from products in App Store Connect to the paywall, is laid out on the iOS in-app subscription page.

If you're getting ready for your first release, take the free diagnostic: it tells you what's really blocking your project and sends you my Apple anti-rejection checklist.

Frequently asked questions

What is Apple's Retention Messaging API?

It's a server-to-server service that picks the message shown to a subscriber when they tap Cancel Subscription. The message appears on a confirmation page, before the cancellation. It can remind them of the subscription's value, offer another plan or a promotional offer.

Is Retention Messaging available to all developers?

The API is a preview, available on request from Apple. At WWDC26, Apple announced a module in App Store Connect, open to everyone, planned for fall 2026. As of November 3, 2026, App Store Connect Help doesn't describe it yet.

Which iOS versions show the message?

iOS 15.1 and iPadOS 15.1 or later, visionOS 1 and macOS 14 or later. On an older device, the cancellation happens with no message.

Does the message stop the subscriber from canceling?

No. The confirmation page keeps a cancel button. The subscriber can also keep their subscription, or accept the offer or plan being proposed.

Can you offer a discount at cancellation time?

Yes. With the API, that's a promotional offer message, real time only: the offer is created in App Store Connect and signed by your server. The module announced in App Store Connect also allows a message with an offer. The plan switch, on the other hand, offers another subscription from the same group.

How many characters for a retention message?

The title is 66 characters max, the body text 144. You can add up to five bullet points and a PNG image without transparency. Each language needs its own default message.

Do you need a server to use Retention Messaging?

No endpoint to host for default messages: you just call the API to upload and set them. With RevenueCat, it acts as the server. Real time requires an HTTPS endpoint that responds in under 700 ms. The module announced in App Store Connect is configured without code.