# Retention Messaging API Provide a reason for customers to stay subscribed with a preconfigured message that you can choose in real time, appropriate to the product and locale. ## Overview The Retention Messaging API is a server-to-server service that enables you to select which message the system displays to customers when they view a subscription details page and might cancel. You upload and configure messages in advance for products and locales. > Important: > To learn more about this pre-release and express interest, see [Request access to the Retention Messaging API](https://developer.apple.com/contact/request/retention-messaging-api/). Your messages remind customers about the features or content they have access to with the subscription, or show them alternative offers. There are four types of retention messages: - A text-based message that can include bullet points - A text-based message that can include bullet points, with an image - A switch-plan message, which contains text and a suggested subscription the customer may choose to switch to - A promotional-offer message, which contains text and a promotional offer to continue service at a discounted price, either at the same or a different tier of service The system displays the retention message to the customer after they tap Cancel Subscription on a subscription details page. The system displays a Confirm Cancellation page where the customer can continue to cancel by tapping Cancel Subscription. They can also tap Keep Subscription, or, depending on the retention message, they can choose to redeem an offer or subscribe to a subscription you suggest. The following four examples show text-based messages on the Confirm Cancellation screen. The first row, from left to right, shows a text-based message without an image, and a text-based message with an image: ![A diagram of an iOS screen in portrait orientation. The screen shows a generic icon, the Confirm Cancellation heading, and a statement that explains when the service ends if you cancel. A section titled From the developer contains a text-only redemption message with a header. The screen has two buttons at the bottom for Cancel Subscription and Keep Subscription.](images/com.apple.retentionmessaging/cancel-messaging-text-only~dark@2x.png) ![A diagram of an iOS screen in portrait orientation. The screen shows a generic icon, the Confirm Cancellation heading, and a statement that explains when the service ends if you cancel. A section titled From the developer contains an image, a header, and redemption message text. The screen has two buttons at the bottom for Cancel Subscription and Keep Subscription.](images/com.apple.retentionmessaging/cancel-messaging-image-with-text-first~dark@2x.png) The next row shows two text-based messages that each include an image, a header above the image, and message text, with the second example also including bullet points: ![A diagram of an iOS screen in portrait orientation. The screen shows a generic icon, the Confirm Cancellation heading, and a statement that explains when the service ends if you cancel. A section titled From the developer contains a header, an image, and redemption message text. The screen has two buttons at the bottom for Cancel Subscription and Keep Subscription.](images/com.apple.retentionmessaging/cancel-messaging-text-with-image-first@2x.png) ![A diagram of an iOS screen in portrait orientation. The screen shows a generic icon, the Confirm Cancellation heading, and a statement that explains when the service ends if you cancel. A section titled From the developer contains a header, an image, and redemption message text that includes bullet points. The screen has two buttons at the bottom for Cancel Subscription and Keep Subscription.](images/com.apple.retentionmessaging/cancel-messaging-bullet-points@2x.png) The following two examples show a switch-plan message and a promotional-offer message on the Confirm Cancellation screen: ![A diagram of an iOS screen in portrait orientation. The screen shows a generic icon, the Confirm Cancellation heading, and a statement that explains when the service ends if you cancel. A section titled From the developer contains a switch-plan redemption message, including a Subscribe button. The screen has two buttons at the bottom for Cancel Subscription and Keep Subscription.](images/com.apple.retentionmessaging/cancel-messaging-plan-switch-recommendation@2x.png) ![A diagram of an iOS screen in portrait orientation. The screen shows a generic icon, the Confirm Cancellation heading, and a statement that explains when the service ends if you cancel. A section titled From the developer contains a promotional-offer redemption message, including a Redeem button. The screen has two buttons at the bottom for Cancel Subscription and Don't Cancel.](images/com.apple.retentionmessaging/cancel-messaging-offer@2x.png) You use the API to select retention messages for customers in two ways: - By configuring default messages, which are text-based messages, with or without an image or bullet points, that apply to specific products and locales. - By choosing a retention message in real time, when you respond to a server-to-server call from the App Store server. You also configure default messages, which the system uses as a fallback if real-time calls fail for any reason. The system doesn’t display a retention message for a product in any locale that lacks a default retention message. ### Upload images and messages All retention messages start with text that you upload, and optional images. For more information, see [`Upload Image`](/documentation/RetentionMessaging/Upload-Image) and [`Upload Message`](/documentation/RetentionMessaging/Upload-Message). Don’t upload content that is misleading or inaccurate. ### Configure default retention messages The simplest way to use this API is to configure default messages. Start by uploading images and messages. Then, specify the messages to use as default messages. For more information, see [Setting up retention messages](/documentation/RetentionMessaging/setting-up-retention-messages). Default messages can display only text-based messages with or without images or bullet points. To provide retention messages that include offers, use the real-time messaging flow. ### Provide real-time messages, including offers The real-time messaging flow calls your server when an active subscriber views a subscription details page with a Cancel button. For example, customers might consider canceling on the Apple Account > Subscriptions page, or when viewing the subscription details page on the App Store. The real-time call informs you about the subscription, including the original transaction ID, and the customer’s locale. You respond by selecting an appropriate preconfigured message for the system to display. You can choose from all the retention message types, including those with switch-plan or promotional offers. Follow these steps to implement the real-time flow: 1. Upload and prepare your retention messages. For more information, see . 1. Configure a default retention message for every product in each locale. The system requires the default messages to use as a fallback if a real-time call to your server fails for any reason. For more information, see ``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/Configure-Default-Message``. 1. Implement the `Get Retention Message` endpoint on your server, and set it up in the sandbox environment by calling the ``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/Configure-Realtime-URL`` endpoint. For more information, see . 1. To set up your endpoint in the production environment, call the ``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/Initiate-Performance-Test`` and pass the test. Then call the ``doc://com.apple.retentionmessaging/documentation/RetentionMessaging/Configure-Realtime-URL`` endpoint to set up your production URL. 1. Respond to App Store requests by selecting a retention message to display in real time. For more information, see . ### System requirements Retention messages are visible only to devices running iOS 15.1 or later, iPadOS 15.1 or later, visionOS 1 or later, or macOS 14 or later. Before you can configure your real-time URL for the production environment, your server needs to pass the performance test. For more information, see [Setting up your Get Retention Message endpoint](/documentation/RetentionMessaging/setting-up-retention-messaging-endpoint). ## Topics ### Essentials [Setting up retention messages](/documentation/RetentionMessaging/setting-up-retention-messages) Upload images and messages for retention messaging, configure default messages, and complete the setup for promotional-offer and switch-plan messages. [Identifying rate limits](/documentation/RetentionMessaging/identifying-rate-limits) Recognize the rate limits that apply to Retention Messaging API endpoints, and handle them in your code. [Retention Messaging API changelog](/documentation/RetentionMessaging/retention-messaging-changelog) Learn about new features and updates in the Retention Messaging API. ### Image configuration [`Upload Image`](/documentation/RetentionMessaging/Upload-Image) Uploads an image to use for retention messaging. [`Delete Image`](/documentation/RetentionMessaging/Delete-Image) Deletes a previously uploaded image. [`Get Image List`](/documentation/RetentionMessaging/Get-Image-List) Gets the image identifier and state for all uploaded images. [`GetImageListResponse`](/documentation/RetentionMessaging/GetImageListResponse) A response that contains status information for all images. [`GetImageListResponseItem`](/documentation/RetentionMessaging/GetImageListResponseItem) An image identifier and state information for an image. ### Message configuration [`Upload Message`](/documentation/RetentionMessaging/Upload-Message) Uploads a message to use for retention messaging. [`Delete Message`](/documentation/RetentionMessaging/Delete-Message) Deletes a previously uploaded message. [`Get Message List`](/documentation/RetentionMessaging/Get-Message-List) Gets the message identifier and state of all uploaded messages. [`UploadMessageRequestBody`](/documentation/RetentionMessaging/UploadMessageRequestBody) The request body for uploading a message, which includes the message text and an optional image reference and bullet points. [`UploadMessageImage`](/documentation/RetentionMessaging/UploadMessageImage) The definition of an image with its alternative text. [`GetMessageListResponse`](/documentation/RetentionMessaging/GetMessageListResponse) A response that contains status information for all messages. [`GetMessageListResponseItem`](/documentation/RetentionMessaging/GetMessageListResponseItem) A message identifier and status information for a message. ### Default message configuration [`Configure Default Message`](/documentation/RetentionMessaging/Configure-Default-Message) Configures a default message for a specific product in a specific locale. [`Get Default Message`](/documentation/RetentionMessaging/Get-Default-Message) Gets the default message for a specific product in a specific locale, if it’s configured. [`Delete Default Message`](/documentation/RetentionMessaging/Delete-Default-Message) Deletes a default message for a product in a locale. [`DefaultConfigurationRequest`](/documentation/RetentionMessaging/DefaultConfigurationRequest) The request body that contains the default configuration information. [`DefaultConfigurationResponse`](/documentation/RetentionMessaging/DefaultConfigurationResponse) The response body that contains the default configuration information. ### Real-time retention messaging setup [Setting up your Get Retention Message endpoint](/documentation/RetentionMessaging/setting-up-retention-messaging-endpoint) Choose retention messages for customers in real time by implementing an endpoint on your server that responds to requests from the App Store server. [`Configure Realtime URL`](/documentation/RetentionMessaging/Configure-Realtime-URL) Configures the URL for your Get Retention Message endpoint in the sandbox and production environments. [`Get Realtime URL`](/documentation/RetentionMessaging/Get-Realtime-URL) Gets the URL for real-time messages that points to your Get Retention Message endpoint, which you previously configured. [`Delete Realtime URL`](/documentation/RetentionMessaging/Delete-Realtime-URL) Deletes the URL for your Get Retention Message endpoint, in the sandbox or production environments. [`RealtimeUrlRequest`](/documentation/RetentionMessaging/RealtimeUrlRequest) The request body for configuring the URL of your Get Retention Message endpoint. [`RealtimeRequestBody`](/documentation/RetentionMessaging/RealtimeRequestBody) The request body the App Store server sends to your Get Retention Message endpoint. [`RealtimeUrlResponse`](/documentation/RetentionMessaging/RealtimeUrlResponse) The response body that contains the URL for your Get Retention Message endpoint. ### Real-time retention messaging responses [Responding to real-time retention messaging requests](/documentation/RetentionMessaging/responding-to-realtime-retention-messaging-requests) Select retention messages for customers in real time by responding to requests on your Get Retention Message endpoint. [`DecodedRealtimeRequestBody`](/documentation/RetentionMessaging/DecodedRealtimeRequestBody) The decoded request body the App Store sends to your server to request a real-time retention message. [`RealtimeResponseBody`](/documentation/RetentionMessaging/RealtimeResponseBody) A response you provide to choose, in real time, a retention message the system displays to the customer. ### Server performance testing [`Initiate Performance Test`](/documentation/RetentionMessaging/Initiate-Performance-Test) Initiates a performance test of your Get Retention Message endpoint in the sandbox environment. [`Get Performance Test Results`](/documentation/RetentionMessaging/Get-Performance-Test-Results) Gets the results of the performance test for the specified identifier. [`PerformanceTestRequest`](/documentation/RetentionMessaging/PerformanceTestRequest) The request object you provide for a performance test that contains an original transaction identifier. [`PerformanceTestResponse`](/documentation/RetentionMessaging/PerformanceTestResponse) The performance test response object. [`PerformanceTestResultResponse`](/documentation/RetentionMessaging/PerformanceTestResultResponse) An object the API returns that describes the performance test results. ### Data types [Data types](/documentation/RetentionMessaging/data-types) Refer to these data types for request and response payloads. ### Error information [Error codes](/documentation/RetentionMessaging/error-codes) Understand the error codes that Retention Messaging API responses return. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)