Apple Retention Messaging

In the Retention Messaging section within Integrations, you can configure Apple's Retention Messaging API for subscribers who intend to cancel.

What the API does

Apple's Retention Messaging API lets you choose which message appears on the App Store's cancellation confirmation screen after a customer taps Cancel Subscription. You can use it to remind subscribers what they keep with their plan, reinforce product value, or present an alternate product or offer that may reduce churn.

Apple supports text-only messages, messages with images, switch-plan messages, and promotional offers. In Superwall, you use this integration to configure the callback URL Apple calls, create retention messages, set default message mappings, and define real-time configurations.

Examples of retention messaging in the cancellation flow:

Apple Callback URL

The dashboard generates a callback URL using your app's public API key:

https://retention-messaging-api.superwall.com/v1/message/<public-api-key>

Use this as the Retention Messaging URL in App Store Connect for your app.

1. Copy the callback URL from Retention Messaging in Superwall.
2. Request access from Apple for the Retention Messaging API.
3. In App Store Connect, open your app's subscription settings and paste the URL into the Retention Messaging URL field.
4. After Apple approves access, contact Superwall support to enable message configuration in the dashboard.

The callback URL does not change when you switch between Production and Sandbox in the dashboard. The environment selector applies to messages, default mappings, and real-time configurations.

Messages

Use Messages to create and manage the retention message payloads that Superwall sends to Apple.

These messages are the records referenced by Default Messages and Real-time Configurations.

Create a message

When you create a message, the dashboard asks for:

• Name: internal label shown in Superwall.
• Environment: Production or Sandbox.
• Locale: for example, en-US.
• Header
• Body
• Alt Text (optional)
• Image Identifier (optional)

The messages table shows the Apple review state for each message: PENDING, APPROVED, REJECTED, or UNKNOWN.

Create the message for the correct environment and locale before adding a default mapping or real-time configuration that references it. The message picker only shows matches for the selected environment and locale.

Preview a message

After a message exists, open the three-dot menu in the messages table and choose the preview action to see a live preview. The preview shows the message payload beside an example cancellation screen, so you can check the header, body, locale, image, and alt text before using the message in a default mapping or real-time configuration.

Default Messages

Use Default Messages to define fallback message mappings by product and locale.

Use a default mapping when you want Apple to show a specific message whenever there is no matching real-time configuration for that product.

Create a default mapping

To create a default mapping:

1. Choose the environment.
2. Select one or more products.
3. Enter the locale.
4. Choose a message. The picker only shows messages for the same environment and locale.
5. Save the mapping.

The dashboard lets you create mappings for multiple products in one action.

Real-time Configurations

Use Real-time Configurations to map product and locale combinations to the retention message behavior Apple should use at runtime.

Supported configuration types

Two real-time configuration types are supported:

• Message: Apple uses the linked retention message.
• Alternate Product: Apple uses the linked message together with an alternate product.

Create a real-time configuration

To create a configuration:

1. Enter a name.
2. Choose the environment.
3. Select one or more products.
4. Enter the locale.
5. Choose the type.
6. If the type is Alternate Product, choose the alternate product.
7. Choose a message. The picker only shows messages for the same environment and locale.
8. Create the configuration.

The dashboard lets you create configurations for multiple products in one action.

If a real-time configuration exists for a product, Apple uses that behavior instead of the default message mapping. When no real-time configuration applies, Apple falls back to the default message.

Reporting

Superwall reports on the retention messages it serves. Reporting appears in two places: overview cards on this page, and two charts in Charts.

Overview cards

Once an app has retention messaging set up, two cards appear at the top of the Retention Messaging page:

• Save Rate: the percentage of retention messages sent where the subscriber did not cancel within 24 hours.
• Total Saves: the number of those subscribers.

Each card draws a sparkline for the selected period and compares it against the previous period of the same length. Selecting a card opens the matching chart with the same environment and date range applied.

Both cards follow the environment and date range selectors in the page header. The date range defaults to the last 30 days. The comparison is hidden when the previous period had no sends, since there is nothing to compare against.

The cards appear once the app has at least one message, message group, or real-time configuration. Apps that have only configured the callback URL do not see them.

Charts

Two charts break the same data down further. Both appear under Retention & Churn in Charts, and only for iOS apps, since Apple's Retention Messaging API is iOS only.

• Retention Messaging Save Rate: percentage of sent messages where the subscriber did not cancel within 24 hours.
• Retention Messaging Saves: count of saved subscriptions, broken down by what the subscriber did next.

Both charts support breakdowns by Product, Environment, Retention Message, Retention Configuration, Response Type, Retention Locale, and Save Outcome. Every one of those except Save Outcome can also be used as a filter, along with Retention Message Group and Retention Configuration Group.

How sends and saves are counted

• A message sent is one realtime request from Apple that Superwall answered with a message, a switch plan, or a promotional offer. Requests answered with no match, and requests that errored, are not counted.
• Sends are deduplicated to one per subscription per calendar day in UTC, keeping the last message served that day. A subscription messaged on three separate days counts as three sends.
• A send is a save when no cancellation is recorded for that subscription within 24 hours of the message.
• Rates across a multi-day range are recomputed from the summed counts rather than averaged across days.