Skip to content
AppDues
Log in
Contact salesSign up

Apple Retention Messaging API: How Real-Time Cancellation Messages Work

When a subscriber opens iOS subscription settings and chooses to cancel, Apple can show an approved message, offer, or alternative plan before the cancellation is confirmed. This guide explains the timing constraint, the choice between App Store Connect and the real-time API, how to target and test messages, and the setup steps needed to go live.

How the real-time flow works

Apple checks whether a default retention message exists for the specific product and locale. If one does, it sends the subscriber's transaction information to the configured backend and waits for a response. The server has under 700 milliseconds to return a message, an alternate product, or a promotional offer. A valid real-time response takes priority. If it cannot be used, Apple falls back to the App Store Connect configuration, or to the API default when no App Store Connect configuration exists. Every message variant must be approved by Apple in advance, so the decision at cancellation time is which approved variant to display, not writing new copy in the moment. The real-time sequence involves identifying the app, product, and subscriber; checking for a configured message, offer, or alternate product; applying eligibility rules covering first seen, first purchase, storefront, trial or introductory-offer status, and offer history; and returning the selected message to Apple.

App Store Connect or the API: choosing the right approach

A retention message can be text only, text with an image, an alternative product such as a lower-priced tier, a promotional offer such as a discount, or a plan switch combined with a promotional offer. App Store Connect supports messages, images, and retention offers with built-in offer-eligibility controls, but does not support audience targeting by trial status, different copy with and without an offer, suggesting another plan, A/B testing, automatic translation, or editing all locales in one screen. The real-time API adds control over which message each subscriber sees and whether an alternative plan is suggested. Choose App Store Connect for a first message without an API integration. Choose the API when you need different copy for trial users and paying subscribers, separate copy for people who receive an offer and those who do not, an experiment comparing approaches, automatic translation, or centralized management across products and locales.

Targeting messages and offers by audience

Audience filters combine customer details such as total spending, first-purchase date, or custom attributes with details of the subscription being canceled. Eligibility can also depend on whether the subscription being canceled is in a free trial or introductory offer, the storefront it belongs to, and whether promotional offers were redeemed previously. Each of these checks is evaluated against the specific subscription the customer is canceling, so a customer with several subscriptions can qualify for a different message on each one. Within a single group, every condition must be satisfied (AND); across separate groups, satisfying any one group is sufficient (OR). A practical starting point is trial cancellations: use the free-trial filter to give trial users a reminder of included benefits, while long-time subscribers receive a different reason to stay. Separate copy can also distinguish subscribers who receive an offer from those who do not, for example by reserving a discount for subscribers who have not redeemed a promotional offer in the last 30 days. When more than one message might qualify, review both the rules and their sequence: outside an experiment, the qualifying real-time message created first is the one served, and the default applies when nothing qualifies. Verify with a sandbox subscriber that the intended rules match the intended audience.

Testing messages and measuring what happens after a save

Start with one specific hypothesis and change one meaningful element at a time, such as comparing a clearer benefits reminder with current copy, or testing whether adding a discount saves enough subscribers to justify the lower price. Compared messages need compatible products, locales, and audience rules. Save rate is the primary metric, with realized lifetime value per customer and churned subscribers as secondary metrics. Subscribers not included in an experiment still receive the message selected by the normal retention configuration; they are not a control group that sees no message. An experiment therefore compares messages and offers against each other, not retention messaging against a cancellation screen with no message. After a save, also review offer acceptance, the share still active and set to renew, churn, and realized lifetime value per customer. Realized lifetime value is revenue observed so far, not a prediction of eventual spending, and results need time to develop. A discount may raise the immediate save rate while reducing later revenue, so weigh both outcomes before choosing a winner. Reporting definitions can differ between Apple and the platform, so check definitions before comparing totals.

What a custom build requires, and what can be managed

Building the integration from scratch means configuring default messages for every product and locale manually, maintaining an always-on backend that responds in under 0.7 seconds and handles promotional-offer signing, and tracking which messages are configured and approved for each product and locale. The orchestration, performance, and data management all remain the developer's responsibility. A managed setup can instead handle uploading messages and default text per locale, generating translations automatically, monitoring message status through the Apple API, and responding within the latency limit, with campaigns configured under Lifecycle, then Retention, without backend code. Campaigns can be tailored by storefront, introductory-offer status, or subscriber tenure.

Setup checklist: from access request to production

First, the Apple Developer account holder requests API access from Apple using the endpoint URL and app information in the setup instructions. Creating a message in App Store Connect does not automatically grant real-time access, so approval is still required. While waiting, prepare messages and a localization strategy. Second, connect the sandbox real-time URL under Lifecycle, then Retention, for the App Store app, and run Apple's performance test with an active sandbox or TestFlight purchase. The test can take up to an hour, so choose a subscription that stays active throughout; a purchase made with a local StoreKit Configuration file will not work. Third, create a default message covering the relevant products, with title and body text for each locale and an image if used. This fallback should make sense for everyone on those products. Automatic translation can fill other locales, followed by review before submission. Fourth, create real-time messages with a reference name and the active subscription product. An alternate plan, a promotional offer, or both can be added; with neither, the message is text with an optional image. Promotional offers are configured in App Store Connect, then associated with the message and active product. Add audience rules and localized copy to complete the message. Fifth, test the cancellation flow for each subscription and audience, verifying copy, locales, offers, and fallback behavior. Then configure the production URL after passing the performance test. Sandbox and production use separate configurations, so check production messages and Apple approval statuses before going live. Configure App Store Server Notifications as well: messages can be delivered without them, but accurate retention charts need them.

Message types, image requirements, and supported devices

Supported message types are: a text message highlighting subscription features or benefits; a text message with an image alongside it, using a 3840 by 2160 PNG with no transparency; a switch-plan message suggesting an alternative subscription plan with a short message; a promotional-offer message offering a discounted price at the same or a different tier with a short message; and a switch-plan message with a promotional offer for that plan. Messages are visible on iOS 15.1 or later, iPadOS 15.1 or later, visionOS 1 or later, or macOS 14 or later. They appear after the user taps Cancel Subscription on the subscription details page. On the Confirm Cancellation screen, the user can complete the cancellation, tap Don't Cancel, or, depending on the message, redeem an offer or switch to a suggested subscription.

App Store Connect compared with the real-time API
CapabilityApp Store ConnectReal-time API
Show messages, images, and discountsYes, including retention offers for discountsYes
Target messages by audience, including trialsNo, offer eligibility rules onlyYes
Use different copy with and without an offerNoYes
Suggest another subscription planNoYes
A/B test messagesNoYes
Auto-translate messagesNo, translations entered manuallyYes
Edit all locales in one screenNoYes

Based on the comparison in the source material; App Store Connect supports messages, images, and retention offers with offer-eligibility controls only.

Frequently asked questions

App Store Connect or the API? The answer depends on how much control you need.

Retention messages can now be configured directly in App Store Connect without a server integration. Real-time delivery through the API remains available by request. The two approaches can work together: start with App Store Connect, then add real-time messages for selected subscribers or products while keeping the existing configuration.