Apple Retention Messaging

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

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.

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.