Configure retention messages

1. From Apps, select your app.

2. In the sidebar, under Monetization, click Subscriptions.

3. Scroll to the Retention Messaging section and click the add button (+). For first-time setup, click Get Started.

4. Enter a unique reference name for your message. Use this name to manage the message in App Store Connect — it isn’t visible to subscribers.

5. Click Create.

6. On the retention message details page, enter header text that introduces your message, such as highlighting value or encouraging subscribers to stay. The page defaults to your app’s primary language.

7. Enter body text with additional details, such as explaining key features, announcing upcoming content, or addressing reasons to remain subscribed. Because all subscribers see this text, do not reference specific offers or prices.

8. Add additional localizations. Use the language menu at the top of the page to switch locales, then repeat steps 6 and 7 for each language you want to support. Ensure your message includes localizations for all storefronts where your subscription is offered.

9. Click Save to save your progress without submitting, or continue to add an image, subscriptions, and offers before submitting for review. After adding your text, use the preview tool to see how your message appears to subscribers.

An app can have up to 10 retention messages. If you reach this limit, delete an existing message before you create a new one. Deleting a retention message can’t be undone.

Adding an image is optional. If you don’t associate an offer with your message, or a subscriber isn’t eligible for any associated offer, the subscriber sees your image alongside your text.

1. From Apps, select your app.

2. In the sidebar, under Monetization, click Subscriptions.

3. Scroll to the Retention Messaging section and click the retention message you want to edit.

4. On the retention message details page, go to the Image section.

5. Choose an image from your Asset Library, or upload a new image. Supported image sizes are 3840 × 2160 pixels or 5244 × 2950 pixels.

6. Click Save.

Choose which subscriptions display your retention message. You can associate an unlimited number of subscriptions with a retention message, keeping in mind that each subscription can have only one active retention message at a time. Then, optionally add one or more retention offers to each subscription.

1. From Apps, select your app.

2. In the sidebar, under Monetization, click Subscriptions.

3. Scroll to the Retention Messaging section and click the retention message you want to edit.

4. On the retention message details page, go to the Subscriptions & Offers section and click the add button (+), or click Choose Subscriptions and Offers if you haven’t added any subscriptions yet.

5. Select one or more subscriptions to associate with this message, then click Add. If you select a subscription that’s already associated with another message, it’s removed from that message after your changes are saved.

6. To associate a retention offer with a subscription, click Add Retention Offer, then choose to create a new offer or select from existing offers already set up for that subscription.

A retention offer gives eligible subscribers a discount or a free period as an incentive to stay subscribed. Eligible subscribers see the offer instead of your message’s image, if you’ve added one. You can create up to 10 retention offers for each subscription billing plan type.* Of those, you can associate up to all 10 with a single retention message.

1. From Apps, select your app.

2. In the sidebar, under Monetization, click Subscriptions.

3. Scroll to the Retention Messaging section, then click the retention message you want to edit.

4. On the retention message details page, next to the subscription you want to add an offer to, click Add Retention Offer.

5. Choose to create a new retention offer or select from existing offers already set up for that subscription, then click Next.

6. If you’re creating a new offer, do the following:

   • Enter a reference name for the offer. Use this name to manage the offer in App Store Connect. After you create the offer, you can’t change the reference name.

   • Enter an offer identifier. Use this identifier to track sales associated with the offer in Sales and Trends reports and in StoreKit transactions. After you create the offer, you can’t change the offer identifier.

   • Click Next.

7. Set subscriber eligibility. Enter a value for Paid Subscription Duration to specify the minimum length of time a subscriber must have maintained a paid subscription before they qualify for the offer. If you want the subscriber to wait before redeeming the same offer, enter a value for Wait Between Offers, then click Next.

   Wait Between Offers applies to each offer individually, not across the subscription. If a subscriber qualifies for more than one offer on the same subscription, they may receive another offer without waiting.

8. Select the countries or regions where you want to make your offer available, then click Next.

9. Choose Pay as you go, Pay up front, or Free, then choose the duration and a price for your default country or region. To search a larger list of price points, click See Additional Prices.

10. Click Next. App Store Connect calculates prices for all remaining selected countries or regions based on the most recent foreign exchange rates. You can choose a different price for individual countries or regions.

11. Review the details of your offer, then click Add. Your offer is associated with this retention message and subscription.

* Billing plan type refers to either a standard billing plan or a monthly with 12-month commitment plan for 1-year subscriptions.

As you add text, an image, subscriptions, and offers, use the preview tool to see how your retention message looks to subscribers. You can submit a retention message as soon as you add text. An image and a retention offer are both optional, and you can add either at any time, before or after your first submission.

1. On the retention message details page, find the preview tool on the right side of the page.

2. Click the card and device buttons to switch between a card view and a view of how the message appears on iPhone or iPad.

3. Choose an option from the Subscription menu to preview how the message appears for a specific subscription.

4. If the subscription has associated offers, choose an offer from the Offer menu to preview how the message will appear to subscribers, or choose None to preview the version of the retention message for ineligible subscribers.

5. Click the expand button to open the preview in full screen.

6. After you’re satisfied with your text, image, and associated subscriptions and offers, click Add for Review. View a list of Retention Message statuses.

Content guidelines for retention messages

Your retention message header and body text must, like other metadata, comply with the App Review Guidelines, including providing content that is accurate and relevant, and not objectionable.

Make sure your copy is clear, direct, and free of specific offer or pricing details. Header and body text can’t reference promotional offers, discounts, or specific prices, such as “$9.99,” “50% off,” or “one month free.” Because all subscribers see this text, including those who aren’t eligible for an associated offer, App Review rejects retention messages that contain pricing or offer mentions.

You can describe what a subscriber loses if they cancel, provided the statement is factual. For example, statements such as “You’ll lose access to downloaded content when your subscription ends” or “After your subscription ends, you won’t have access to premium features” are acceptable.

Avoid claims that coerce subscribers or guarantee unverifiable outcomes. For instance, don’t claim that canceling a VPN service will result in a virus infection. Softer variations of these claims—such as suggesting a device becomes more susceptible to threats—as well as unverified superlative or statistical claims like “the best app” or saying without support that “92% of parents report improved learning,” are strongly discouraged. As a best practice, use standard capitalization and punctuation, and avoid excessive emphasis such as all-caps text or repeated exclamation marks.

Once a retention message is approved and published, you can still edit its text and image. Editing an approved message creates a new draft version alongside the published version, rather than replacing it right away.

1. From Apps, select your app.

2. In the sidebar, under Monetization, click Subscriptions.

3. Scroll to the Retention Messaging section, then click the retention message you want to edit. To view a list of your retention offers, click View Subscription Pricing, then click the Retention Offers tab.

4. On the retention message details page for a published message, click New Version and then click Create.

5. The page shows two statuses at once: the status of your published version, and the status of your in-progress draft version, such as Edits Pending Submission. Make your changes to the text or image, then click Save. When you’re ready to submit your changes, click Add for Review. See Retention Message Statuses.

6. Your approved version continues to display to subscribers, unaffected, while your draft is in progress or in review. However, Sandbox testers always see your latest version, including any unpublished drafts.

7. Click Add for Review to submit your drafts. Once App Review approves it, the draft becomes the new published version and replaces the previous one. You can’t roll back to a previously published version.