WWDC 2026: Explore Retention Messaging in App Store Connect (Session 309)

Configure App Store subscription cancellation-flow retention messages, offers, and real-time server-driven responses with App Store Connect and the Retention Messaging API.

Watch on Apple Developer

TL;DR

Retention Messaging lets apps show a value proposition, image, or offer when a subscriber reaches the cancellation confirmation flow for an auto-renewable subscription.
App Store Connect setup is no-server: create localized message text, optionally attach Asset Library images and retention offers, map the message to one or more subscriptions, and test in sandbox.
Real-time Retention Messaging adds server-to-server decisioning through the Retention Messaging API, including message selection, promotional offers, and switch-plan alternatives within a subscription group.
Use App Store Connect Retention Messaging even with real-time messaging as fallback; real-time production use requires sandbox setup, a passing performance test, production configuration, and requested access.

Retention Messaging targets a specific subscription lifecycle moment: when a customer is about to cancel an auto-renewable subscription in the App Store manage-subscriptions flow. It lets developers present a reminder of subscription value or an incentive to stay subscribed before cancellation is confirmed.

The supported App Store Connect views are message-only, message with image, and message with offer. If a customer is eligible for an offer, the offer presentation replaces the image. Apple describes save rate as the percentage of subscribers who keep their subscription after reaching the cancel confirmation page, and notes that results vary across developers.

Use message text to communicate upcoming features, benefits, or value proposition.
Use Asset Library images for visual reinforcement.
Use retention offers to provide an incentive such as a free period on the current subscription.
A single retention message can be associated with multiple subscriptions.

Configuring Retention Messaging in App Store Connect

App Store Connect adds a Retention Messaging area on the Subscriptions page. Developers create a named retention message, edit localized title and description text, optionally choose an image from Asset Library, select applicable subscriptions, and attach eligible retention offers. A live preview updates as the configuration changes.

The App Store automatically chooses the best eligible offer when multiple retention offers are selected for a subscription. Retention messages are testable in sandbox by canceling a sandbox subscription.

Message text is required; image and offer are optional.
Localizations can be configured for message content.
Retention offers must already be configured before selecting them for the message.
App Store Connect API support is mentioned for setting up retention messages and retention offers.

Testing and transaction fields for retention offers

Retention offers are introduced as a new offer type for retention messages. When a retention offer is redeemed, signed transaction and renewal information include offer-related fields, including a new offerType value of 5. Sandbox testing can verify both the cancellation-flow presentation and the transaction or renewal-info fields.

Check offerIdentifier, offerDiscountType, and offerPeriod when validating redemption behavior.
Use sandbox cancellation flows before moving retention messages to production.
Treat offerType = 5 as the signal that a redeemed offer was a retention offer.

Signed transaction fields for a redeemed retention offer

A retention offer redemption appears in signed transaction or renewal info with offerType 5 and the usual offer metadata.

{
  "bundleId": "com.example.app",
  "productId": "Yoga_summer_2026",
  "type": "Auto-Renewable Subscription",
  "transactionReason": "RENEWAL",
  "offerType": 5,
  "offerIdentifier": "Yoga_2026_cancel_free_3m",
  "offerDiscountType": "FREE_TRIAL",
  "offerPeriod": "P3M",
  "transactionId": "1000098916194",
  "originalTransactionId": "1000011859217"
}

Real-time Retention Messaging with the Retention Messaging API

Real-time Retention Messaging uses a server-to-server HTTP request from the App Store when a customer is about to cancel. Your server responds with a preference for what the App Store should show. This enables per-customer decisioning instead of relying only on a static App Store Connect configuration.

The Retention Messaging API is used in sandbox and production to configure the app endpoint URL, create and manage messages, upload and manage images, and set default messages per subscription. Performance testing endpoints are available in sandbox only, and passing a sandbox performance test is required before using real-time Retention Messaging in production.

The App Store request includes identifiers such as originalTransactionId, appAppleId, productId, userLocale, requestIdentifier, environment, and signedDate.
Response options include message, alternateProduct, and promotionalOffer.
alternateProduct supports switch-plan messaging for another product in the same subscription group.
Promotional offers used in retention messages still require a promotional offer signature.
Access to real-time Retention Messaging is requested through the linked interest form.

Retention Messaging API endpoint categories

The API manages endpoint configuration, messages, defaults, images, and sandbox-only performance tests.

// Base: https://api.storekit.apple.com/inApps/v1/messaging

// URL configuration
PUT /realtime/url
GET /realtime/url
DELETE /realtime/url

// Message configuration
PUT /message/{messageIdentifier}
DELETE /message/{messageIdentifier}
GET /message/list

// Defaults
PUT /default/{productId}/{locale}
DELETE /default/{productId}/{locale}
GET /default/{productId}/{locale}

// Images
PUT /image/{imageIdentifier}
DELETE /image/{imageIdentifier}
GET /image/list

// Sandbox performance testing
POST /performanceTest
GET /performanceTest/result/{requestId}

Real-time request and message response

A basic real-time response selects a configured message, optionally paired with an image.

// Request from the App Store
{
  "originalTransactionId": "123456789",
  "appAppleId": 6745974591,
  "productId": "Yoga_summer_2026",
  "userLocale": "en-US",
  "requestIdentifier": "c03248af-dd76-4e9b-9c1e-4489cd19a768",
  "environment": "Production",
  "signedDate": 1780920000000
}

// Your response
{
  "message": {
    "messageIdentifier": "551ee7c0-c097-418e-9dd5-2a98533a7390"
  }
}

Choosing between App Store Connect and real-time messaging

The main difference is decisioning. App Store Connect Retention Messaging lets the App Store show the configured message and applicable offer without another server call. Real-time Retention Messaging lets your server choose what to show for each cancellation attempt.

Fallback behavior makes App Store Connect configuration valuable even when using real-time messaging. The App Store prioritizes a valid real-time response. If that response is unavailable or malformed, it falls back to the App Store Connect Retention Messaging preference, including eligible offers. If no App Store Connect message is configured, it falls back to default messaging configured with the Retention Messaging API.

Choose App Store Connect Retention Messaging if you do not have a server or want App Store-managed selection.
Choose real-time Retention Messaging if you have a fast server and need per-customer message, offer, or switch-plan decisions.
Real-time messaging supports the same message/image/offer concepts plus a switch-plan view.
For iOS 26.5 monthly subscriptions with a 12-month commitment, real-time alternateProduct responses can include billingPlanType to offer that plan type as a switch plan.
Keep production messages and images up to date after enabling real-time production responses.

Real-time alternate product and promotional offer responses

Real-time responses can offer a switch plan in the same subscription group or a signed promotional offer.

// Switch plan response
{
  "alternateProduct": {
    "messageIdentifier": "ed7f25fc-5741-46a3-8502-062e0fb8afd0",
    "productId": "Yoga_summer_2026_annual"
  }
}

// Promotional offer response
{
  "promotionalOffer": {
    "messageIdentifier": "80135e2b-ae15-4ec4-8c5c-9ecc8045c0dc",
    "promotionalOfferSignatureV2": "eyJhbGciOiJFUzI..."
  }
}

Explore Retention Messaging in App Store Connect