Contents

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.

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:

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:

The following two examples show a switch-plan message and a promotional-offer message on the Confirm Cancellation screen:

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

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 Setting up retention messages.

  2. 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 Configure Default Message.

  3. Implement the Get Retention Message endpoint on your server, and set it up in the sandbox environment by calling the Configure Realtime URL endpoint. For more information, see Setting up your Get Retention Message endpoint.

  4. To set up your endpoint in the production environment, call the Initiate Performance Test and pass the test. Then call the Configure Realtime URL endpoint to set up your production URL.

  5. Respond to App Store requests by selecting a retention message to display in real time. For more information, see Responding to real-time retention messaging requests.

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.

Topics

Essentials

Image configuration

Message configuration

Default message configuration

Real-time retention messaging setup

Real-time retention messaging responses

Server performance testing

Data types

Error information

Type Aliases