Promoted in-app purchases: App Store setup, code and testing

Promoted in-app purchases let you show an in-app purchase, such as a subscription, a premium unlock or a level pack, directly on the App Store. They appear on your product page, can show up in App Store search as their own result, and may be picked for the Today, Games and Apps tabs. Someone can tap one and start buying before they have even installed your app.

Few indie apps use them, which is exactly why they are worth an afternoon. Each promoted purchase is another way to appear in search and another chance to explain what your app is worth paying for. This guide covers what Apple requires, the StoreKit code to complete a purchase that starts on the App Store, the App Store Connect steps, how to test it before release, and the problems developers run into. Everything is quoted from Apple's documentation, linked where it appears.

Key takeaways

• You can promote up to 20 in-app purchases at a time. Each one needs an approved purchase, a 1024 x 1024 image, a display name of up to 30 characters and a description of up to 45.
• Consumables never appear in search results. Subscriptions, non-consumables and non-renewing subscriptions can.
• Your app must handle PurchaseIntent (iOS 16.4 and later). Without it, a promotion shown to all users "won't be visible on the App Store."
• Test the flow with an itms-services://?action=purchaseIntent link before you ship.
• Use Product.PromotionInfo to hide purchases a person already owns.

What promoted in-app purchases are, and where they appear#

Apple's marketing page for promoted purchases puts it simply: "Promoted Apple In-App Purchases appear on your product page, can display in search results, and may be featured on the Today, Games, and Apps tabs." It adds one important exception: "consumable Apple In-App Purchases will not appear in search results."

When someone taps a promoted purchase, StoreKit takes over. According to Apple's StoreKit guide, "If your app isn't installed when the user selects to purchase the in-app product, the App Store automatically downloads the app or prompts the user to purchase it." If an older version of your app is installed, the App Store asks the person to update first. Then your app opens and completes the purchase.

Every promoted purchase is one more entry point into your app from the App Store. Photo: Sanket Mishra / Pexels

Why they matter for ASO#

Your app normally gets one result in App Store search. Apple's search guidance says search can also return "developer cards, Apple In-App Purchases, In-App Events, and custom product pages." A well-named promoted subscription or unlock gives you another result for searches that match it, with its own image instead of your screenshots. That makes it one of the few levers that adds visibility without changing your app name or keywords. Our guide to App Store ranking factors explains where it fits among the others.

It also helps conversion. A visitor who sees "Pro Yearly, includes all templates" on your product page knows what the upgrade is before installing, which is more honest and often more persuasive than a paywall they discover later.

What you need before you start#

From Apple's App Store Connect help on promoting in-app purchases:

• Approved purchases. "All In-App Purchases and metadata must be approved by App Review."
• A limit of 20. "You can promote up to 20 In-App Purchases on their App Store product page simultaneously, in all countries or regions."
• An image for each. "You must add an image in order to promote an In-App Purchase."
• The right role. Account Holder, Admin, App Manager, Developer or Marketing.
• Code in your app. "Your app must support the PurchaseIntent API in order for the App Store to display your promoted product pages."

The image, name and description#

Apple's specs for the promotional assets:

Apple's guidance on the image is specific: it "should not be screenshots, and should not be confused with your app icon," and Apple recommends you "don't overlay text on the image." It also warns to avoid putting important details in the lower-left corner, where the frame can cover them. For the name, Apple discourages generic labels like "100 gems." Say what the person gets.

Treat the display name like a tiny piece of ASO. "Pro Yearly: Unlimited Scans" is clearer to a searcher than "Premium", and it matches what people type.

Step 1: Handle PurchaseIntent in your app#

When someone buys on the App Store, StoreKit opens your app and delivers the product through PurchaseIntent.intents, an asynchronous sequence available from iOS 16.4. Your job is to call purchase() on that product and handle the result like any other purchase. Apple's minimal example:

for await purchaseIntent in PurchaseIntent.intents {
    do {
        try await purchaseIntent.product.purchase()
    } catch {
        // Handle the error
    }
}

In a real app, start listening at launch and deal with the case Apple calls out: the person may arrive in the middle of onboarding. Apple says, "To defer the transaction, store the purchase intent and process it later." A small handler can do both:

import StoreKit

@MainActor
final class PromotedPurchaseHandler {
    private var pendingIntent: PurchaseIntent?
    var isOnboarding = false

    // Call once at app launch.
    func startListening() {
        Task {
            for await intent in PurchaseIntent.intents {
                if isOnboarding {
                    pendingIntent = intent  // finish onboarding first
                } else {
                    await buy(intent.product)
                }
            }
        }
    }

    func onboardingDidFinish() async {
        isOnboarding = false
        if let intent = pendingIntent {
            pendingIntent = nil
            await buy(intent.product)
        }
    }

    private func buy(_ product: Product) async {
        do {
            let result = try await product.purchase()
            if case .success(let verification) = result,
               case .verified(let transaction) = verification {
                // Unlock the content, then finish the transaction.
                await transaction.finish()
            }
        } catch {
            // Tell the user what went wrong.
        }
    }
}

Two rules from Apple's guide are easy to miss:

• Do not ignore the intent silently. If the person already owns the product, show a message. Apple notes that without feedback, "the app's lack of action after the user initiates the purchase on the App Store may seem like a bug."
• Pick one API. For iOS 11 to 16.3, the older route is paymentQueue(_:shouldAddStorePayment:for:) on SKPaymentTransactionObserver. Apple says to use either that or PurchaseIntent, and "Don't use both at the same time."

If you build with React Native, Flutter or a purchases SDK, check that your library supports App Store promotions on iOS before you turn them on. Most popular SDKs expose a hook for purchases that start on the App Store, but it is usually opt-in.

The code change is small, but without it Apple will not show the promotion to everyone. Photo: Daniil Komov / Pexels

Step 2: Turn the promotion on in App Store Connect#

Apple's App Store Connect steps, condensed:

1. In Apps, select your app. In the sidebar under Monetization, click In-App Purchases (or Subscriptions for subscriptions).
2. Open the purchase you want to promote and scroll to App Store Image. Click Choose File and upload the 1024 x 1024 image.
3. Click Promote on the App Store and choose who sees it: everyone, "even those who don't have the app installed," or only people who meet conditions you set in the app.
4. Tick the Promoted checkbox for each purchase, and drag them into the order you want on your product page.
5. Click Save.

Then wait. Apple says to "Allow up to 24 hours for changes to reflect on your App Store product page," and a purchase that is pending approval may not appear yet.

Step 3: Show the right promotions to each person#

By default, every promoted purchase shows on every device. With Product.PromotionInfo, you can change the order and visibility per device, for example to hide something the person already bought. This example is from Apple's StoreKit guide:

let purchasedProductIdentifier = "com.example.ExampleApp.product1"

do {
    try await Product.PromotionInfo.updateProductVisibility(.hidden, for: purchasedProductIdentifier)
} catch {
    // Handle the error
}

These overrides are per device and "take effect after the user launches the app at least once." A game can show only the level pack for the player's current level; a productivity app can hide the monthly plan from someone who already pays yearly. Using PromotionInfo is optional: Apple says it "isn't required for your promoted Apple In-App Purchases to appear on the App Store."

Step 4: Test before you ship#

You do not have to wait for the App Store to test the flow. Apple's testing guide provides a system URL:

itms-services://?action=purchaseIntent&bundleId=com.example.app&productIdentifier=com.example.product

Replace the bundle ID and product ID, send the link to yourself by email or iMessage, and open it on a device with your build installed. "You'll know the test is running when your app opens automatically." Test three cases: the app in the foreground, the app closed, and the app in the middle of onboarding.

Subscriptions, intro offers and win-back offers#

Promoted subscriptions do more than show a price. Apple says that if an auto-renewable subscription is promoted, "the introductory price will display on the App Store for eligible customers." Lead with the free trial in the display name or image only if every new subscriber actually gets it.

Win-back offers for lapsed subscribers can also be shown on the App Store. Apple's win-back guide says customers "can also discover and redeem win-back offers in the App Store," and requires an approved subscription image if you promote the offer there. PurchaseIntent has an offer property for exactly this case. If you run offers already, our guide to App Store offer codes covers the other ways to reach the same people.

Common problems and fixes#

• The promotion does not appear at all. Check that the purchase and its metadata are approved, that 24 hours have passed, and that your released build handles PurchaseIntent. Apple warns that if you show the promotion to everyone "but haven't implemented the PurchaseIntent API, your In-App Purchase won't be visible on the App Store."
• It appears on the product page but not in search. Consumables never appear in search results. Search also depends on whether the name matches what people type.
• Your handler never fires. On the RevenueCat community, a developer wrote that they "just can't seem to get" the promoted product method "to ever be called." Their fix was to create the App Store promotion in App Store Connect and test with that product's ID. Also make sure you start listening at launch, not on a later screen.
• It does not show on Apple Vision Pro. Apple says promoted purchases "aren't available to compatible iPad or iPhone apps running in visionOS."
• The image is rejected or looks wrong. Remove text overlays, keep it distinct from your icon, and keep details out of the lower-left corner.

Your promoted in-app purchases checklist#

• Pick up to 20 purchases worth promoting, starting with your main subscription or unlock.
• Write a specific display name (30 characters) and description (45 characters).
• Design a 1024 x 1024 image that is not a screenshot or your icon.
• Handle PurchaseIntent from app launch, with deferral during onboarding.
• Hide owned purchases with Product.PromotionInfo.
• Test with the itms-services:// link in all three app states.
• Ship the build, then turn on the promotion in App Store Connect and wait 24 hours.
• Watch purchases and product page conversion in App Store Connect analytics for the following weeks.

Promoted purchases sit alongside your other product page assets. If you are refreshing those too, see our guides to the new App Store creative assets and App Store screenshot sizes. And for reach beyond the store, you can list your iOS app on the AppRanker leaderboard, where position is a plain sort on what each listing has paid and every row links straight to your App Store page.

FAQ#

What are promoted in-app purchases?#

They are in-app purchases you choose to show on the App Store itself: on your product page, in search results (except consumables), and potentially on the Today, Games and Apps tabs. People can start the purchase on the App Store, and your app completes it.

How many in-app purchases can I promote?#

Up to 20 at a time on your product page, in all countries or regions. You can keep more approved and ready to swap in.

Do promoted in-app purchases need App Review?#

The purchases and their metadata must be approved by App Review before they can appear. Changes can take up to 24 hours to show on your product page.

Why is my promoted in-app purchase not showing?#

The most common causes are a purchase still pending approval, a build that does not handle PurchaseIntent, a consumable (which never shows in search), or the 24-hour delay after saving changes.

Do promoted in-app purchases help App Store ranking?#

They do not change how your app itself ranks, as far as Apple has said. They give you additional entries that can appear in search results, with their own name and image, which adds visibility for searches that match them.

Does Google Play have promoted in-app purchases?#

Not as search results. The closest tools are promotional content (events and offers shown on Google Play, available to games and larger apps) and promo codes. Our guide on how to get featured on Google Play covers promotional content.

Image credits#

• Cover, woman holding an iPhone and a bank card: photo by Karola G on Pexels, Pexels License. Cropped to 1200x630.
• Siri Suggestions with the App Store icon: photo by Sanket Mishra on Pexels, Pexels License. Cropped.
• Code editor on a laptop: photo by Daniil Komov on Pexels, Pexels License. Cropped.