# Apple Retention Messaging

Configure Apple's Retention Messaging API in Superwall, including the callback URL, messages, default message mappings, and real-time configurations.

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

> **Warning:** Apple must **first** approve your app for the Retention Messaging API before you can use this integration
> in production — Superwall cannot grant this access.After Apple has approved your app, contact
> [Superwall Support](https://support.superwall.com) to enable full message configuration in the
> dashboard. Until then, only the callback URL is available.

## What the API does

Apple's [Retention Messaging API](https://developer.apple.com/documentation/retentionmessaging)
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:

![Retention messaging examples on Apple](https://2b001d9a-superwall-docs-staging.staffbar.workers.dev/docs/images/retention-messaging-example.png)

## 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](https://developer.apple.com/contact/request/retention-messaging-api/)
   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](#default-messages) and
[Real-time Configurations](#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.

![Retention message live preview in Superwall](https://2b001d9a-superwall-docs-staging.staffbar.workers.dev/docs/images/retention_preview_view.jpg)

## 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.

> **Note:** The UI disables products that already have a default mapping in the selected environment.
> If a product is unavailable, delete its existing mapping before creating another one.

## 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.

> **Note:** The UI disables products that already have a real-time configuration in the selected
> environment. If a product is unavailable, delete its existing configuration before creating
> another one.

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.