Retention-message body copy cannot name a price or offer — every subscriber sees that text, including people who are not eligible for the offer
Apple posted Now available: Retention messages for subscriptions on 4 November 2026. In Apple’s words, the messages “remind subscribers of your subscription's value as they decide whether to cancel,” and they “appear in the cancellation flow and can include text, images, or a special offer.” Apple first presented the feature in the WWDC26 session Explore Retention Messaging in App Store Connect. What is new is that you can now configure it in App Store Connect.
Retention messages, now available as of 4 November 2026, appear in the cancellation flow — not after the subscriber has already left. Header and body text are shown to every subscriber who starts cancellation, including people who are not eligible for an associated offer, so App Review rejects copy that names promotional offers, discounts, or specific prices (Apple’s examples: “$9.99,” “50% off,” “one month free”). Eligible subscribers see a retention offer instead of the image, not in addition to it; an app may have up to 10 messages, and a subscription may have only one active message at a time. The Retention Messaging API, which can choose a message per subscriber, is available by request — it is not on by default.
When subscribers see the message
Apple’s help page says retention messages reach subscribers “at the point of cancellation”: they appear when a subscriber starts to cancel. The person has not left yet. This is not a message to people who have already cancelled or lapsed. Write copy for someone who is still subscribed and deciding.
Why the shared text cannot carry an offer
Each message has required header and body text. The Configure retention messages help page says: “Because all subscribers see this text, do not reference specific offers or prices.” Its content guidelines add that App Review rejects messages that mention pricing or offers, because ineligible subscribers see the same text. Keep prices, discounts, and offer names out of the header and body. The offer module is the only place for an offer. Do not write “eligible-only” wording into the shared fields and hope the offer module covers it.
What you *can* say: Apple allows factual statements about what a subscriber loses, for example “You’ll lose access to downloaded content when your subscription ends” or “After your subscription ends, you won’t have access to premium features.” Apple discourages coercive or unverifiable claims, including softer versions of them and unsupported superlatives or statistics. It also recommends standard capitalization and punctuation, with no all-caps or repeated exclamation marks. Like other metadata, the text must still follow the App Review Guidelines. For the latest guideline revision, see our 16 October 2026 guidelines article.
Three layouts, never image plus offer
A subscriber who starts to cancel sees one of three layouts:
- Text only: header and body, no image or offer.
- Text and an image: you added an image, and either no offer is associated or the subscriber is not eligible for any associated offer.
- Text and a retention offer: at least one offer is associated and the subscriber is eligible. Eligible subscribers see the offer *instead of* the image.
Retention offers are set up at the subscription level, but subscribers see them only through a retention message. An offer you create but never associate with a message is never shown. App Store Connect offers three types, Pay as you go, Pay up front, or Free, each with a duration and a price per country or region. Images are optional; the supported sizes are 3840 × 2160 or 5244 × 2950 pixels.
Caps and assignment
An app can have up to 10 retention messages. At the limit, you must delete one before you create another, and deletion cannot be undone. One message can cover many subscriptions, but each subscription has only one active message at a time. If you add a subscription that already belongs to another message, it is removed from that message when you save.
Eligibility is per offer
Paid Subscription Duration sets the minimum time a subscriber must have paid before they qualify. Wait Between Offers is optional, and Apple says it “applies to each offer individually, not across the subscription.” A subscriber who qualifies for more than one offer on the same subscription may get another offer without waiting. It is not a cooldown for the whole subscription.
Review, drafts, and sandbox
Every message goes through App Review. You can submit as soon as the text is in; the image and offers can be added before or after the first submission. Editing an approved, published message creates a new draft version next to the published one. Subscribers keep seeing the approved version while the draft is in progress or in review. Once App Review approves the draft, it replaces the published version, and you cannot roll back to an earlier published version. Sandbox testers always see the latest version, including unpublished drafts, so a sandbox screenshot does not show what production subscribers see. The Retention message statuses page lists each stage, from Prepare for Submission to Approved, plus the two combined statuses shown while an edit is pending.
The Retention Messaging API is a separate, by-request layer
The news post says: “With the Retention Messaging API, you can choose which message to show each subscriber based on their subscription details. API access is available by request.” Setting eligibility and wait times in App Store Connect does not turn this API on. The Retention Messaging API documentation calls it a pre-release, server-to-server service with two modes:
- Default messages: text-based messages, with or without an image or bullet points, set per product and locale. Messages configured in App Store Connect take precedence over these defaults. Default messages cannot carry offers.
- Real-time selection: when an active subscriber views a subscription details page with a Cancel button, the App Store server calls your endpoint. According to Responding to real-time retention messaging requests, the request includes details such as the product ID, locale, and original transaction ID. Your server must reply within 700 ms in production. If the request fails, the system shows the message and offer configured in App Store Connect, if there is one, and otherwise your default message. A real-time choice takes precedence over both defaults and App Store Connect messages. Before you can set a production URL, your server must pass Apple’s performance test.
The documentation also says retention messages are visible only on iOS 15.1 or later, iPadOS 15.1 or later, visionOS 1 or later, and macOS 14 or later. It links the access request from the API overview. That request page requires an Apple sign-in, so we have not seen its fields.
What to do this month
- In App Store Connect, go to Apps → your app → Monetization → Subscriptions → Retention Messaging. You need the Account Holder, Admin, App Manager, or Marketing role.
- Write a header and body that state the value of the subscription or a factual line about what the subscriber loses. Leave out prices, discounts, and offer names. If you use the App Store Connect API, the header is limited to 66 characters and the body to 144.
- Add a localization for every storefront where the subscription is offered.
- In the preview tool, check two states separately: the Offer menu set to None, which is what ineligible subscribers see, and each associated offer as an eligible subscriber sees it. Then submit for review.
- Plan your 10 message slots and the one-active-message-per-subscription rule before you create messages, because deletion is permanent.
- If you need a different message for each subscriber, request API access. App Store Connect alone does not do this.
- Treat an edit as a new review: the live version stays up until the draft is approved, and you cannot roll back after that.
What this article is not
It is not a tutorial on offers for subscribers who have already cancelled, and it is not pricing strategy. It is not the Guideline 3.1.2(c) paywall article and not a reread of the App Review Guidelines. It is not legal advice.
Not legal advice. Wording is quoted or paraphrased from Apple’s public news post, App Store Connect Help, and the Retention Messaging API and App Store Connect API documentation, all read on 10 November 2026. Follow the current pages and preview both states before you submit.
Sources
- Now available: Retention messages for subscriptions (4 November 2026)
- Configure retention messages
- Retention message statuses
- Retention Messaging API
- Responding to real-time retention messaging requests
- Setting up retention messaging for auto-renewable subscriptions (App Store Connect API)
- Explore Retention Messaging in App Store Connect (WWDC26)