---
name: promoted-iap
description: Generates Promoted In-App Purchase setup with StoreKit 2 product configuration, paywall integration, and App Store product page display. Use when setting up promoted purchases that appear on the App Store product page.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
last_verified: 2026-07-16
review_by: 2027-06-22
os_version: iOS 27 / macOS 27
---

# Promoted In-App Purchases Generator

Set up promoted In-App Purchases so your premium offerings appear directly on your App Store product page, in search results, and in editorial features.

## When This Skill Activates

Use this skill when the user:
- Asks to "promote IAP" or "show purchase on product page"
- Mentions "promoted in-app purchase" or "App Store product page IAP"
- Wants subscription/IAP visible in App Store search results
- Asks about `paymentQueue(_:shouldAddStorePayment:for:)`
- Wants to handle purchases initiated from the App Store

## Pre-Generation Checks

### 1. Project Context Detection
- [ ] Check for existing StoreKit implementation
- [ ] Check deployment target (iOS 15+ for StoreKit 2)
- [ ] Look for existing IAP product definitions
- [ ] Check if `paywall-generator` was already used

### 2. Conflict Detection
```
Glob: **/*Promoted*.swift, **/*StorePayment*.swift
Grep: "shouldAddStorePayment" or "PurchaseIntent" or "promotedPurchase"
```

## How Promoted IAP Works

1. **App Store Connect**: Mark IAP products as "Promoted" with promotional image
2. **Product Page**: Up to 20 promoted IAPs appear on your product page
3. **Search Results**: Promoted IAPs can appear in search
4. **User Action**: User taps "Buy" on App Store → your app opens to complete purchase
5. **Your App**: Must handle the incoming purchase intent

### Promoted IAP Display Order
- You control the order in App Store Connect
- Choose your most compelling IAP as the first promoted product
- Apple may also feature your IAPs in editorial content

## Configuration Questions

Ask user via AskUserQuestion:

1. **What type of IAP to promote?**
   - Auto-renewable subscription
   - Non-consumable (one-time unlock)
   - Consumable (credits/tokens)

2. **How to handle App Store-initiated purchases?**
   - Show immediately (direct purchase)
   - Show paywall first (let user see options before buying)
   - Show onboarding then purchase (new users from App Store)

3. **Number of promoted products?**
   - Single product
   - Multiple products (2-5)
   - Full catalog (6+)

## Generation Process

### Step 1: Read Templates
Read `templates.md` for promoted IAP implementation code.

### Step 2: Create Core Files

1. **PromotedPurchaseHandler.swift** — Handle purchases initiated from App Store
2. **PromotedProductConfiguration.swift** — Product definitions and promotional images specs
3. **PromotedPurchaseFlowView.swift** — UI for completing promoted purchases in-app

### Step 3: Determine File Location
```
- If Sources/Store/ exists → Sources/Store/Promoted/
- If Store/ exists → Store/Promoted/
- Otherwise → Store/Promoted/
```

## Output Format

### Files Created
```
Store/Promoted/
├── PromotedPurchaseHandler.swift        # App Store purchase handling
├── PromotedProductConfiguration.swift   # Product setup & image specs
└── PromotedPurchaseFlowView.swift       # In-app purchase completion UI
```

### Integration Steps

**Handle App Store-Initiated Purchases (StoreKit 2):**
```swift
@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .task {
                    // Listen for purchases initiated from App Store
                    for await purchaseIntent in PurchaseIntent.intents {
                        await PromotedPurchaseHandler.shared.handle(purchaseIntent)
                    }
                }
        }
    }
}
```

**Complete the Purchase:**
```swift
// PromotedPurchaseHandler determines the right flow:
// 1. Direct purchase (existing user, known product)
// 2. Paywall (show options first)
// 3. Onboarding (new user from App Store)
```

### App Store Connect Setup

1. Go to App Store Connect > Your App > In-App Purchases
2. Select the IAP product
3. Under "App Store Promotion":
   - Upload promotional image (1024x1024, no alpha, no rounded corners)
   - Set display order
   - Enable promotion
4. Repeat for each product you want to promote

### Promotional Image Requirements
- **Size**: 1024 x 1024 pixels
- **Format**: PNG or JPEG, no transparency
- **Content**: Feature the product value, not just the app icon
- **Text**: Minimal — the product name appears separately
- **Style**: Match your app's visual identity

### Testing Instructions

1. **StoreKit Configuration**: Add promoted products to your .storekit file
2. **Test purchase flow**: Simulate App Store-initiated purchase
3. **Test user states**: New user, existing free user, existing subscriber
4. **Verify UI**: Purchase completion view looks correct for each product type

## References

- **templates.md** — Production Swift templates
- Related: `generators/paywall-generator` — Full paywall for purchase completion
- Related: `generators/subscription-offers` — Offer types for promoted subscriptions
- Related: `app-store/marketing-strategy` — Strategic product promotion planning


---
Source attribution: rshankras
Original project: https://github.com/rshankras/claude-code-apple-skills/blob/9ffb83138209057875698dd11c1720c657c47a92/skills/generators/promoted-iap/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2025 Ravishankar

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: rshankras
Original project: https://github.com/rshankras/claude-code-apple-skills/blob/9ffb83138209057875698dd11c1720c657c47a92/skills/generators/promoted-iap/SKILL.md
Attribution basis: Source repository record

Fields of work: Development & Engineering, Marketing
Roles: Mobile Developer, Product Marketer
Specialties: API, Mobile
Tools: Storekit
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 6774dc27304cfa3adc2dc74e288582ff957c9801336904a7be9e485fbd7f5fde