# 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 [#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:
Apple Callback URL [#apple-callback-url]
The dashboard generates a callback URL using your app's public API key:
`https://retention-messaging-api.superwall.com/v1/message/`
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 [#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 [#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 [#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 [#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 [#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 [#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 [#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 [#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.