rshankras/subscription-offers

Subscription Offers Generator

Generate complete StoreKit 2 implementation for all four subscription offer types with eligibility verification, offer presentation, and transaction handling.

When This Skill Activates

Use this skill when the user:

• Asks to "add subscription offers" or "set up free trial"
• Mentions "introductory offer", "promotional offer", or "offer codes"
• Wants "StoreKit 2 offers" implementation
• Asks about "subscription pricing" or "discounted subscription"
• Mentions "preferredSubscriptionOffer" or "eligibility check"

Pre-Generation Checks

1. Project Context Detection

• [ ] Check for existing StoreKit implementations (import StoreKit)
• [ ] Check deployment target (iOS 16.4+ for SubscriptionStoreView offers, iOS 15+ for manual)
• [ ] Look for existing product/subscription group IDs
• [ ] Identify if paywall-generator was already used

2. Conflict Detection

Glob: **/*Offer*.swift, **/*Eligibility*.swift
Grep: "introductoryOffer" or "promotionalOffers" or "winBackOffers"

If existing offer code found, ask:

• Extend with additional offer types?
• Replace existing implementation?

Offer Types Reference

1. Introductory Offers

• Who: New subscribers who haven't previously subscribed
• Types: Free trial, pay-as-you-go, pay-up-front
• Limit: One per subscription group per Apple ID
• StoreKit 2: product.subscription?.introductoryOffer

2. Promotional Offers

• Who: Current or lapsed subscribers. Baseline eligibility is deliberately broad — any current or lapsed subscriber of any subscription in the app, even mid-intro — so layer YOUR business rules on top
• Types: Free, pay-as-you-go, pay-up-front (pay-up-front prices are deliberately NOT price-validated — this is what enables bundle-style pricing)
• Limit: Up to 10 active offers per subscription
• Requires: Server-side signature generation — sign server-side only; signatures are valid 24 hours, so generate just before display
• StoreKit 2: product.subscription?.promotionalOffers
• Attribution: identify redemptions by offerType (1 = introductory, 2 = promotional, 3 = offer code) + offerIdentifier

3. Offer Codes

• Who: Anyone with a valid code (you distribute)
• Types: Free or discounted period
• Limit: Configurable per campaign in App Store Connect
• StoreKit 2: try await AppStore.presentOfferCodeRedeemSheet()

4. Win-Back Offers

• Who: Previously subscribed users who churned
• Types: Free or discounted period
• Eligibility: Automatic via App Store (iOS 18+)
• StoreKit 2: product.subscription?.winBackOffers

Offer Strategy (Apple's Data)

• Intro offers work: 60% of active paid subscriptions began with an introductory offer — mostly free trials, outside Greater China.
• Trial length follows category norms — match what customers in your category already expect:

| Typical trial | Categories | |---------------|------------| | ~1 month | Entertainment, social, music, books | | 1 week | Health & fitness, productivity, education, weather | | 3 days | Photo/video, games, utilities, business |

• …and regional norms: monthly trials dominate in the US/Canada/Europe/Australia/NZ; 7-day in Greater China/Japan/Latin America; 3-day in Southeast Asia and EMEA.
• Annual pricing: ~33% off the effective monthly rate is the cited pattern — "12 months for the price of 8".
• Reduce trial anxiety: show an in-app countdown of trial days remaining and offer an opt-in push reminder before the trial converts.
• ❌ Never hard-code offer merchandising ("Try 1 week free") — check isEligibleForIntroOffer and render only offers the user can actually redeem.

The Six Churn Playbooks (WWDC19 — still the strategy canon)

| Playbook | Trigger | Move | |----------|---------|------| | Win-back | Subscription expired | Offer on relaunch / re-engagement | | Retention | Auto-renew flipped off — you get the server notification the moment it flips | Save offer before expiry | | Upgrade | Downgrade notification received | Nudge back to the higher tier | | Customer-service appeasement | Support flags a bad experience | Offer on next launch | | Loyalty | Long tenure (e.g., a free month at the 11th consecutive renewal) | Surprise reward | | Save | User heads to Manage Subscriptions | Intercept with an offer first |

Configuration Questions

Ask user via AskUserQuestion:

1. Which offer types? (multi-select)

   • Introductory offer (free trial / discounted first period)
   • Promotional offers (targeted discounts for eligible users)
   • Offer codes (redeemable codes you distribute)
   • Win-back offers (re-engage churned subscribers)

2. Introductory offer details (if selected)

   • Free trial: 3 days / 7 days / 14 days / 30 days
   • Pay-as-you-go: discounted rate for X periods
   • Pay-up-front: discounted rate for full period

3. Deployment target

   • iOS 15+ (manual offer UI)
   • iOS 16.4+ (SubscriptionStoreView with offers)
   • iOS 18+ (win-back offer support)

4. Server-side signature (if promotional offers selected)

   • Will you generate signatures server-side?
   • Use App Store Server Library?

Generation Process

Step 1: Read Templates

Read templates.md for all offer implementation code.

Step 2: Create Core Files

1. SubscriptionOfferManager.swift — Central offer management

   • Offer eligibility checking for all types
   • Offer presentation logic
   • Transaction handling for offer purchases

2. OfferEligibility.swift — Eligibility verification

   • Introductory offer eligibility (isEligibleForIntroOffer)
   • Promotional offer eligibility (your business logic)
   • Win-back offer eligibility (iOS 18+)

3. OfferConfiguration.swift — Offer type definitions and configuration

Step 3: Create UI Files (conditional)

4. OfferBannerView.swift — Contextual offer banners

   • Shows appropriate offer based on user state
   • Introductory offer for new users
   • Promotional offer for at-risk subscribers
   • Win-back offer for churned subscribers

5. OfferCodeRedemptionView.swift — Offer code entry UI (if offer codes selected)

Step 4: Create Optional Files

6. OfferSignatureProvider.swift — Server-side signature handling (if promotional offers)
7. OfferAnalytics.swift — Track offer impression, tap, and conversion events

Step 5: Determine File Location

- If Sources/Store/ exists → Sources/Store/Offers/
- If Store/ exists → Store/Offers/
- If Subscriptions/ exists → Subscriptions/Offers/
- Otherwise → Offers/

Output Format

Files Created

Store/Offers/
├── SubscriptionOfferManager.swift    # Central offer management
├── OfferEligibility.swift            # Eligibility verification
├── OfferConfiguration.swift          # Offer type definitions
├── OfferBannerView.swift             # Contextual offer UI
├── OfferCodeRedemptionView.swift     # Code entry (optional)
├── OfferSignatureProvider.swift      # Server signatures (optional)
└── OfferAnalytics.swift              # Offer tracking (optional)

Integration Steps

Check Introductory Offer Eligibility:

let manager = SubscriptionOfferManager()
let isEligible = await manager.isEligibleForIntroOffer(
    productID: "com.app.subscription.monthly"
)

Present Best Available Offer:

// Automatically selects the best offer for the user's state
let offer = await manager.bestAvailableOffer(
    for: "com.app.subscription.monthly"
)

// Use with SubscriptionStoreView (iOS 16.4+)
SubscriptionStoreView(groupID: groupID)
    .preferredSubscriptionOffer(offer)

Present Offer Code Sheet:

// iOS 16+
try await AppStore.presentOfferCodeRedeemSheet()

Win-Back Offer (iOS 18+):

let winBackOffers = await manager.availableWinBackOffers(
    for: "com.app.subscription.monthly"
)
if let bestOffer = winBackOffers.first {
    // Present win-back UI
}

Testing Instructions

1. StoreKit Configuration file: Add offer configurations
2. Test each offer type in Sandbox environment
3. Verify eligibility logic: Test with new, current, and lapsed accounts
4. Test edge cases: Expired trials, multiple subscription groups, family sharing

App Store Connect Setup

1. Go to App Store Connect > Subscriptions > Your Group
2. Introductory Offer: Set in subscription pricing section
3. Promotional Offers: Create under "Subscription Prices" > "Promotional Offers"
4. Offer Codes: Create under "Offer Codes" tab
5. Win-Back Offers: Configure under "Win-Back Offers" (iOS 18+)

References

• templates.md — All production Swift templates
• Related: generators/win-back-offers — Dedicated win-back flow skill
• Related: generators/paywall-generator — Full paywall with offer integration
• Related: app-store/marketing-strategy — Strategic offer planning