/subscription-offers

name: subscription-offers
description: Generates StoreKit 2 code for all subscription offer types — introductory, promotional, offer codes, and win-back. Includes eligibility checks, offer presentation, and the preferredSubscriptionOffer modifier. Use when adding subscription offers, free trials, or promotional pricing.
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

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 offe