Create a retention message

Retention messages allow you to reach out to churning subscribers during the cancellation process. When a customer reaches the iOS Cancel Subscription screen, Apple shows them the message that matches their product and locale.

There are two kinds of retention messages:

Default: A simple win-back message with a headline, body, and an optional image. Used as fallback when a promo message is unavailable.
Promo: A win-back message that offers subscribers a special deal or a different plan. You can only create promo messages for products that already have a Default message assigned.

Before you begin

Create at least one product for the message to cover.
Test Retention Messaging in sandbox mode.

Create a message

Open the Retention Messaging page in the Adapty Dashboard. Click Create Default for a default message, or Create Message for a promo message.

The Create Default and Create Message buttons in the Retention Messaging page header

Select the environment — a sandbox message for testing, or a production message for real users. The production option stays disabled until you configure the production URL and pass the sandbox performance test.

New message start screen with Create a sandbox message and Create a production message options

General

Name the message and add the products that will trigger the message when cancelled.

The product list grays out the products you can’t add, with the reason next to each: used means another message of the same type already covers the product, and no default message means the product needs a Default message before it can get a promo one.

Default message General step with the Name field and Products section

For a promo message, link an incentive to every product you add. One product gets one incentive, and Next stays disabled until each product has one:

Link Promo Offer: A promotional offer you previously set up for the product.
Link Plan Switch: A different product from your catalog. If the plan list is empty, check that you’ve added an App Store Connect API key: Adapty needs it to look up the plans.

Content

Write the message in English. A preview on the right shows the message on the Cancel Subscription screen as you type.

The Default message may include an image. Add Alt text to describe the image for screen readers. Alt text isn’t localized: Apple gets the English alt text in every locale.

By default, the title and body appear below the image. To show the title above the image, select Above the image under Title position. The body always stays below the image.

Content step with an uploaded image, Title position set to Above the image, and a phone preview showing the title above the image

Important

Choose the title position when you create the message. You can’t change it later — to use a different position, create a new message. If you create a message without an image and add one later, the title stays below the image.

Localization

English is the source language. Add the other languages your subscribers use, then translate the content.

Click Add Locale and choose which locales to support.
Click AI Translate All Cells to automatically translate the content. The translation replaces the title and body in every added locale, including your manual edits, so translate first and edit afterwards.
Click any cell to edit a translation.

Every locale must fit the same limits as the English source: 66 characters for the title, 144 for the body. A translation that runs longer blocks Submit To Review until you shorten it.

Hover over a locale to preview it on the Cancel Subscription screen.

Adapty falls back to the en-US version if Apple hasn’t yet approved a translation for the target locale.

Localization step with the locale table and the AI Translate All Cells button

Submit for review

When the message is ready, click Submit To Review. Adapty uploads the message to Apple in every locale that has a title or body, and Apple starts reviewing it. Adapty drops a locale whose cells are both empty. Monitor the status of your submission on the Retention Messaging page.

Adapty saves the message only when you submit it.

Message states

After you submit the message, Apple reviews each locale separately. The message goes live as soon as Apple approves at least one locale. For the locales Apple hasn’t approved yet, Adapty falls back to en-US. The State column on the Retention Messaging page allows you to track the message’s progress:

State	What it means
In review	Apple hasn’t received the message yet, or hasn’t approved any of its locales.
Live	Apple approved the message, and Adapty serves it to cancelling subscribers.
Rejected	Apple turned down the submission in at least one locale — try submitting an alternative version.
Inactive	You deactivated the message. You can now create a new one for the same products.

To see which locales Apple hasn’t approved yet, open the message and go to the Localization step. Each added locale shows its own Live, In review, or Rejected status.

You can edit any message at any time — including messages that are being actively served to your customers. If you edit a Live message, or add a new locale to it, the message instantly loses its live status, and becomes an In review message again.

If you change the English title or body of an existing message, the Content step button changes to Update Locales. Click it to open the Localization step, update the translations, and then click Submit To Review.

Deactivate and reactivate

To remove a message from Apple without deleting it from Adapty, open the menu in the message’s row and click Deactivate.

To bring it back, click Activate. Reactivation skips Apple’s review, and the message can take a few minutes to reach all subscribers.

A product can have at most one default message and one promo message. If another message of the same type claimed the product while this one was inactive, activation fails.

Next steps

Track how the message performs once it goes live.