When a subscriber starts cancelling an auto-renewable subscription from their App Store settings, Apple displays a native retention flow — and asks Purchasely, in real time, what to show to this subscriber.

With Apple Retention Messaging, you answer that moment with:

• a retention message — text, optionally with a hero image or bullet points, localized in the subscriber's language
• a promotional offer — a discounted price to make them stay, signed and served automatically
• a plan switch proposal — a better-suited plan (e.g. switch a monthly subscriber about to churn to a discounted yearly plan)

Everything is server-driven: no SDK update and no app release are needed. The feature is available for App Store subscriptions, and is managed from the Retention Messages section of the Purchasely Console.

How it works

1. The subscriber taps Cancel subscription in their App Store settings.
2. Apple calls Purchasely in real time.
3. Purchasely evaluates your targeting rules in priority order and answers with the first matching rule's action: a message, a promotional offer, or a plan switch proposal.
4. Apple natively displays the response. When no rule matches, Apple displays the default message you configured for the product and locale.

Every request is recorded as a RETENTION_MESSAGE_REQUESTED server event, so you can measure the cancel funnel and the performance of your retention strategy (see Measuring below).

Prerequisites

• An iOS app with auto-renewable subscriptions on the App Store.
• The In-App Purchase key configured on your app in the Purchasely Console (the same key used for StoreKit 2) along with your app's Apple ID.
• Access to Apple's Retention Messaging API, granted by Apple per app (see below).

Requesting access from Apple

Apple's Retention Messaging API is currently available through a pre-release program: access must be requested from Apple, per app, through Apple's request form.

1. Only the Account Holder of your Apple Developer account can fill out the form.
2. Provide your app's name, its Apple ID (App Store Connect → App Information), and the endpoint URL — this is the realtime URL shown in the Setup tab of the Purchasely Console, ready to copy.
3. Select "My app currently has a subscription on the App Store", then submit.

Apple notifies you once your request is approved; you can then proceed with the setup below.

Setting up

Open your app in the Purchasely Console → Retention Messages → Setup tab. The setup is a one-time, per-environment flow:

1. Register the realtime URL with Apple for the sandbox environment. The URL is generated by Purchasely — one click, nothing to host.
2. Run the performance test. Apple requires a passing performance test before accepting a production URL; the test runs in sandbox and needs an active sandbox (or TestFlight) subscription in your app. It takes about an hour: Apple exercises the endpoint across different configurations, including concurrent calls — you can leave the page and come back, the Setup tab shows the last test result.
3. Register the production URL once the test has passed.

The Setup tab also shows your message slots usage — Apple limits the number of retention messages per app.

Creating messages

From the Messages tab, a retention message is authored once and translated into as many locales as you serve; each localization is submitted to Apple and reviewed individually (statuses: In review, Approved, Rejected). Only approved localizations are served to subscribers.

• In sandbox, Apple approves messages automatically — you can test the full flow instantly.
• In production, each localization goes through Apple's review before it can be displayed.
• Message content is immutable once submitted: to change a message, delete it and create a new one.

From the Images tab, you can upload hero images and bullet icons that messages reference; images go through the same Apple approval flow.

Default messages

The default message is what Apple displays when no targeting rule matches the cancelling subscriber. Defaults are assigned per product × locale from the Messages tab: for full coverage, assign a default message to every product and locale you serve. The By product view of the Messages tab shows this as a product × locale matrix, flags every combination left without a default, and lets you assign one by clicking the cell.

Targeting

From the Targeting tab, you decide who sees what with retention audiences and ordered rules:

• A retention audience is a set of criteria on the subscriber's subscription state (plan, trial, subscription age, etc.).
• A targeting rule is an audience plus an action: show a message, offer a promotional offer, or propose a plan switch. Rules are evaluated in priority order — the first rule whose audience matches and whose response can be served wins.

A rule is served when its message has an approved localization for the subscriber's locale (with language fallback, e.g. en-US → en). A promotional offer can retain the subscriber on their current product — or propose a discounted switch to another plan, by using an offer configured on that other plan (Apple applies it like a regular purchase). A switch proposal must target a different plan than the one being cancelled. When a rule does not apply, the next one is evaluated, down to your catch-all rule or the default message.

🚧

Apple constraints to keep in mind

• Messages used in a promotional offer or plan switch rule must be text-only (no image).
• A plan switch proposal must target a plan of the same App Store subscription group as the cancelled product. Purchasely cannot verify subscription groups, so double-check the group when creating a switch rule: a rule targeting a plan of another group would still win its priority slot — preventing your lower-priority rules (like a catch-all message) from being evaluated — while Apple would not display the proposal.

Measuring your retention strategy

Each time Apple requests a retention message, Purchasely emits a RETENTION_MESSAGE_REQUESTED server event carrying what was answered: the response type and the identifiers of the served rule, message, offer or plan (see Server Events Attributes). It is available as a webhook (opt-in), through your configured integrations, and in your analytics.

Combined with the existing lifecycle events, it gives you the full cancel funnel:

• RETENTION_MESSAGE_REQUESTED — the subscriber entered the cancel flow, and this is what was proposed
• RENEWAL_DISABLED then DEACTIVATE — the cancellation was confirmed
• PROMOTIONAL_OFFER_STARTED — the subscriber accepted the retention offer
• plan-change events — the subscriber accepted the switch proposal
• no follow-up event — the subscriber left the cancel sheet and kept their subscription

Apple also provides an aggregate daily retention report (page views, cancels and saves), which complements the per-subscriber view. Note that Retention Messaging is currently API-only on Apple's side: its App Store Connect pages, including this report, are announced by Apple but not live yet.