diff --git a/content/docs/images/retention-messaging-example.png b/content/docs/images/retention-messaging-example.png
new file mode 100644
index 00000000..5123b49e
Binary files /dev/null and b/content/docs/images/retention-messaging-example.png differ
diff --git a/content/docs/integrations/apple-retention-messaging.mdx b/content/docs/integrations/apple-retention-messaging.mdx
new file mode 100644
index 00000000..c898b992
--- /dev/null
+++ b/content/docs/integrations/apple-retention-messaging.mdx
@@ -0,0 +1,138 @@
+---
+title: "Apple Retention Messaging"
+description: "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.
+
+
+ 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:
+
+
+
+## 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
+
+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.
+
+## 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.
+
+
+ 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.
+
+
+ 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.
diff --git a/content/docs/integrations/meta.json b/content/docs/integrations/meta.json
index 9f205291..b149eda0 100644
--- a/content/docs/integrations/meta.json
+++ b/content/docs/integrations/meta.json
@@ -1,22 +1,23 @@
{
- "title": "Integrations",
- "icon": "Puzzle",
- "root": true,
- "pages": [
- "index",
- "---Integrations---",
- "webhooks",
- "apple-search-ads",
- "facebook-pixel",
- "mixpanel",
- "adjust",
- "amplitude",
- "posthog",
- "customer-io",
- "firebase",
- "statsig",
- "slack",
- "discord",
- "figma-plugin"
- ]
-}
\ No newline at end of file
+ "title": "Integrations",
+ "icon": "Puzzle",
+ "root": true,
+ "pages": [
+ "index",
+ "---Integrations---",
+ "webhooks",
+ "apple-search-ads",
+ "apple-retention-messaging",
+ "facebook-pixel",
+ "mixpanel",
+ "adjust",
+ "amplitude",
+ "posthog",
+ "customer-io",
+ "firebase",
+ "statsig",
+ "slack",
+ "discord",
+ "figma-plugin"
+ ]
+}