App Store promoted in-app purchases: how to surface your subscription offer before users even download your app
Apple lets you display up to 20 in-app purchases directly on your App Store product page and in search results. Here's how the mechanic works, which subscription tiers to promote, and how to implement the StoreKit handler that makes it all work.
Most App Store subscription developers focus acquisition strategy entirely on what happens inside the app: paywall design, trial framing, push notification timing. Apple has made it possible to start a subscription purchase flow before a user even opens your app — and most developers haven't touched the feature.
Promoted in-app purchases let you surface up to 20 IAPs directly on your App Store product page and, when Apple chooses to feature them, in search results. A user sees your subscription offer, taps Buy, and Apple handles the rest — installing the app if needed and passing the purchase intent into your code. This guide covers what the feature does, how to configure it, and where it fits into a subscription growth strategy.
What promoted in-app purchases actually are
Apple introduced promoted in-app purchases as part of iOS 11. The feature does two things: it makes selected IAPs visible on your App Store product page as a separate section beneath your screenshots, and it makes those IAPs eligible for Apple's editorial placements in search results and the Today and Apps tabs.
Crucially, the purchase flow starts on the App Store itself. If a user taps your promoted subscription and doesn't have your app installed, the App Store installs the app and queues the purchase — when the app first launches and calls the right StoreKit delegate method, the purchase resumes. For users who already have the app installed, the purchase sheet opens immediately.
Key point: Promoted in-app purchases work with all IAP types — auto-renewing subscriptions, non-renewing subscriptions, consumables, and non-consumables. For most subscription apps, auto-renewing subscriptions are the natural choice to promote, because they represent your recurring revenue and Apple will apply introductory offer eligibility automatically at purchase time.
The App Store product page can show a maximum of 20 promoted IAPs. Apple controls whether any of those appear in search results — that editorial placement is not guaranteed, and Apple does not publish the criteria for selection. What you do control is the order and visibility of promoted IAPs on your own product page.
Setting up promoted IAPs in App Store Connect
Configuring promoted in-app purchases requires two things: App Store Connect setup and a small addition to your StoreKit implementation.
In App Store Connect, navigate to your app's In-App Purchases section, select an existing product, and look for the App Store Promotion tab. Upload a 1024×1024 promotional image — no rounded corners, no transparency, and no device frames; Apple applies the rounded-corner treatment itself. You also set a promotional name of up to 30 characters that can differ from the full product name, which is useful for fitting within the narrow card layout.
Once you've set promotional images for the IAPs you want to surface, go to your app's App Store > Promotions section. This screen lets you drag-and-drop up to 20 IAPs into a ranked order and toggle their visibility. The order you set here determines how they appear on your product page — your highest-value or most-purchased plan should generally lead.
On the code side, you must implement the StoreKit handler that responds to incoming promoted-purchase transactions. Without it, any promoted purchase tapped from the App Store will appear to do nothing — the transaction queues and waits, but your app never responds to it.
For the legacy SKPaymentQueue path, implement paymentQueue(_:shouldAddStorePayment:for:) in your SKPaymentTransactionObserver. Return true to proceed immediately, or return false to defer (for example, if the user hasn't finished onboarding). For StoreKit 2, the equivalent flow uses PurchaseIntent delivered via PurchaseIntent.intents — an AsyncSequence you observe at app launch.
Apple's documentation also notes that you can override the order and visibility of promoted IAPs on a per-device basis using the StoreKit 2 Product.PromotedOrder API. This allows personalisation — for example, surfacing your annual plan first for users who have been on the free tier for more than 30 days.
Which subscriptions to promote and in what order
Not every subscription tier deserves a promoted slot. Users browsing search results or landing on your product page have high intent but limited context — they haven't experienced your core feature loop yet. That context gap changes which offer converts best at this funnel stage.
| What to promote | Why it works at this funnel stage | Risk to watch |
|---|---|---|
| Annual plan with introductory trial | Best value positioning visible immediately; trial removes payment commitment at purchase | Refund rate can be higher for impulse annual purchases without onboarding context |
| Monthly plan with introductory trial | Lower financial commitment; easier decision before experiencing the app | Lower LTV per acquisition; higher churn if the app doesn't deliver quickly |
| Lifetime access (if offered) | One-time payment removes the recurring-charge concern entirely | Only viable if your monetisation model supports it; no renewal revenue |
| Top tier in a good/better/best structure | Anchors high-value users before they see the free experience | Can set feature expectations the app doesn't meet for new users mid-onboarding |
The safest starting point for most subscription apps is to promote the annual plan with an introductory free trial. The trial reduces friction — users can commit knowing they won't be charged immediately — while the annual framing means those who convert are higher-LTV subscribers. If Apple features your app in search for a competitive keyword, the promoted annual plan appears alongside your screenshots and can close the sale without the user reading your description at all.
Introductory offers on promoted IAPs work the same as anywhere else: Apple checks eligibility at purchase time. If a user has already claimed an introductory offer for your subscription group, they won't receive it again through a promoted IAP tap. For a deeper look at introductory offer types and eligibility rules, see the post on iOS subscription introductory offers.
Regional and localisation considerations
Promoted IAP images and names are set per locale in App Store Connect. This is a frequently missed localisation lever. Most developers upload a single English image and promotional name and leave it across all territories. If your app has meaningful user bases in Japan, Germany, Brazil, or South Korea, a localised promotional image — one that shows the value proposition in the local language with locally resonant visual design — is likely to outperform a generic English card.
The 30-character promotional name limit is particularly important for non-Latin scripts. Japanese, Chinese, and Korean pack more meaning into 30 characters than English does, which is an advantage; Arabic and Hebrew require RTL-aware design in the card image itself. A promotional name that simply truncates your English product name is a missed opportunity.
There is no App Store Connect API endpoint for uploading promotional images as of mid-2026 — image assets must be uploaded manually per locale. The promotional name and visibility/order can be updated via the App Store Connect API's inAppPurchasePromotions resource, which means you can script changes to which tiers are featured and in what order without going through the UI. For teams managing pricing updates programmatically, this pairs naturally with the broader price-update automation described in Building a price-update workflow with the App Store Connect API.
If you use a third-party subscription SDK like RevenueCat or Adapty, check their documentation for promoted IAP support before going live. RevenueCat provides a delegate callback that wraps the promoted purchase flow so it resolves within their entitlement management layer rather than bypassing it. Skipping this integration step can result in a purchase that completes on the App Store side but is never reflected in your app's entitlements — a paid user who looks like a free user to your backend.
For territory-specific context on which subscription tier to promote in which market, the post on App Store subscription ARPU by geography provides useful regional benchmarks. The right promoted tier for Japan — where annual plan adoption is comparatively high — may differ from Brazil, where monthly plans reduce the perceived upfront commitment in a market where purchasing-power sensitivity runs high.
Measuring impact and iterating
App Store Connect's Analytics section does not expose a dedicated promoted-IAP conversion funnel as of this writing. You can build measurement from a few available signals:
Product page IAP impressions and taps. App Store Connect Analytics shows per-IAP tap data for your product page, including the promoted IAP section. This tells you which promoted products are generating interest, even if the full tap-to-subscription funnel isn't surfaced natively.
In-app transaction attribution. When the StoreKit promoted-purchase delegate fires, the transaction arrives with the product identifier. You can tag these transactions in your own analytics pipeline — for example, writing a custom attribute like source: "promoted_iap" before resuming the purchase — and compare trial-start and conversion rates against your in-app paywall cohort. For guidance on handling and verifying these transactions with StoreKit 2, see the post on StoreKit 2 for iOS subscriptions.
Refund rate monitoring. Research from RevenueCat and developer data shared by Adapty suggests that purchases made before a user has experienced the app tend to carry a modestly higher short-term refund rate, particularly for annual plans bought on impulse. Monitor your refund rate in the weeks after enabling a promoted annual subscription; if it climbs materially, consider leading with a trial-gated annual plan or switching your promoted lead to the monthly tier.
Iteration speed. Updating the promoted IAP order or visibility in App Store Connect takes effect within minutes — Apple does not require a new app review to change order or visibility. Updating promotional images or names requires review. Plan visual refreshes (for seasonal offers or redesigned cards) with the same one-to-three business day review buffer you would apply to other App Store Connect metadata changes.
Common setup mistakes to avoid
No StoreKit delegate implementation. The most common error. A promoted IAP tap with no handler results in a silent failure — the transaction queues and never resolves. Always implement the handler, even if all it does is return true to pass the transaction straight through immediately.
Promotional image fails review. Apple rejects promotional images that include a device frame, transparency, rounded corners you've applied (Apple adds its own), or text that overlaps required safe zones. Treat the 1024×1024 canvas as a full-bleed flat graphic and keep key text away from the corners.
Promoted product pointing to a deprecated IAP. If you restructure your subscription group — adding tiers, retiring old ones — update your promoted IAP list in App Store Connect at the same time. A promoted IAP pointing to a deprecated product ID will appear on the product page but fail silently at purchase.
Skipping the deferred-purchase path. Some apps require onboarding before they can meaningfully fulfil a subscription — fitness apps that generate a personalised plan, for example. If that's your case, return false from shouldAddStorePayment, save the payment reference, complete onboarding, then manually add the stored payment to the queue. Omitting this step delivers a paying subscriber into a broken onboarding flow.
Sources and further reading
- Apple Developer Documentation — StoreKit framework overview
- Apple Developer Documentation — App Store Connect API reference
- RevenueCat Blog — subscription SDK implementation guides and industry data
- Adapty Blog — iOS subscription analytics, paywall design, and SDK integration
- Phiture Mobile Growth Stack — App Store product page and conversion optimisation research
Share this post
Ready to put this into practice?
AppsOps is the first App Store ops dashboard — PPP-fair pricing for 175 App Store territories, AI metadata localization in 39 languages, AI screenshot localization for 14 Apple device classes, and one-click App Store Connect API push — all from one dashboard, all for $19/month.
Try AppsOps free — no card →