rshankras/win-back-offers

Win-Back Offers Generator

Generate a complete win-back flow for recovering churned subscribers using StoreKit 2's win-back offer APIs (iOS 18+), Message API handling, and fallback promotional offers for older OS versions.

When This Skill Activates

Use this skill when the user:

• Asks to "win back" or "re-engage" churned subscribers
• Mentions "lapsed subscribers" or "subscriber recovery"
• Wants to implement "win-back offers" (iOS 18+)
• Asks about "subscription churn" reduction
• Mentions "Message API" for subscription offers
• Wants to reduce subscriber attrition

Minimum Eligibility

Win-back offers involve meaningful engineering and ASC configuration. Check these thresholds before proceeding:

| Churned Subscribers | Recommendation | |----|---| | Under 50 | Not worth the setup effort. Use personal email outreach instead — write individual messages to churned users. Focus energy on preventing churn (improve onboarding, engagement). | | 50-500 | Implement basic win-back via promotional offers (simpler than full win-back flow). Use offer codes distributed via email. | | 500+ | Full win-back implementation justified. Native iOS 18+ win-back offers, Message API handling, automated pipeline. |

If you don't know your churn numbers: Check App Store Connect > Subscriptions > Retention metrics. If your total subscriber base is under 200, you likely don't have enough churn volume to justify this skill yet.

Pre-Generation Checks

1. Project Context Detection

• [ ] Check for existing StoreKit implementation
• [ ] Check deployment target (iOS 18+ for native win-back, iOS 16+ for promotional offer fallback)
• [ ] Look for existing subscription management code
• [ ] Check if subscription-offers skill was already used
• [ ] Check churn volume — is the number of churned subscribers worth automating?

2. Conflict Detection

Glob: **/*WinBack*.swift, **/*Reengag*.swift
Grep: "winBackOffers" or "Message.messages" or "presentWinBackOffer"

Configuration Questions

Ask user via AskUserQuestion:

1. Win-back approach

   • Native win-back offers only (iOS 18+ required)
   • Promotional offer fallback (supports iOS 16+)
   • Both (recommended)

2. Message handling

   • Handle App Store messages in-app (recommended)
   • Let system handle messages
   • Custom message presentation

3. Analytics integration

   • Basic (print logging)
   • Custom analytics protocol
   • Specific SDK (specify which)

Generation Process

Step 1: Read Templates

Read templates.md for all win-back implementation code.

Step 2: Create Core Files

1. WinBackOfferManager.swift — Win-back offer detection, eligibility, and presentation
2. WinBackMessageHandler.swift — StoreKit Message API integration for in-app offer display
3. WinBackEligibility.swift — Churn detection and eligibility logic
4. WinBackOfferView.swift — Custom win-back offer presentation UI

Step 3: Create Optional Files

5. WinBackAnalytics.swift — Track win-back funnel metrics
6. WinBackFallback.swift — Promotional offer fallback for iOS < 18

Step 4: Determine File Location

- If Sources/Store/ exists → Sources/Store/WinBack/
- If Store/ exists → Store/WinBack/
- Otherwise → WinBack/

Output Format

Files Created

Store/WinBack/
├── WinBackOfferManager.swift      # Core win-back logic
├── WinBackMessageHandler.swift    # Message API handling
├── WinBackEligibility.swift       # Churn detection
├── WinBackOfferView.swift         # Custom offer UI
├── WinBackAnalytics.swift         # Funnel tracking (optional)
└── WinBackFallback.swift          # iOS < 18 fallback (optional)

Integration Steps

App Entry Point — Message Handling:

@main
struct MyApp: App {
    var body: some Scene {
        WindowGroup {
            ContentView()
                .storeMessagesTask { message in
                    // Handle win-back messages from App Store
                    await WinBackMessageHandler.shared.handle(message)
                }
        }
    }
}

Check Win-Back Eligibility:

let manager = WinBackOfferManager()
let winBackOffer = await manager.checkWinBackAvailability(
    productID: "com.app.subscription.monthly"
)

if let offer = winBackOffer {
    // Show win-back UI
    showWinBackSheet(offer: offer)
}

Present Win-Back Offer:

// Native (iOS 18+)
SubscriptionStoreView(groupID: groupID)
    .preferredSubscriptionOffer { product, subscription, offers in
        offers.first { $0.type == .winBack }
    }

Testing Instructions

1. Sandbox Account: Create a subscriber, cancel, wait for expiry
2. StoreKit Testing: Use Transaction Manager to simulate churn
3. Message Testing: Test App Store message presentation
4. Verify flow: Churned → Offer shown → Purchase → Active subscriber

App Store Connect Setup

1. Go to Subscriptions > Your Group > Win-Back Offers
2. Create offer with pricing and duration
3. Set eligibility criteria (days since churn, previous subscription duration)
4. Configure offer priority if multiple offers exist

References

• templates.md — All production Swift templates
• Related: generators/subscription-offers — All offer types including win-back
• Related: generators/paywall-generator — Full paywall implementation
• Related: app-store/marketing-strategy — Win-back campaign planning