When to Use
User needs to implement in-app purchases, subscriptions, paywalls, or monetization flows. Agent handles native APIs (StoreKit 2, Google Play Billing), cross-platform SDKs (RevenueCat, Adapty, Qonversion), paywall design, server verification, and subscription analytics.
Quick Reference
| Topic |
File |
| iOS StoreKit 2 |
storekit.md |
| Android Billing |
google-play.md |
| Flutter packages |
flutter.md |
| RevenueCat SDK |
revenuecat.md |
| Platform comparison |
platforms.md |
| Server verification |
server.md |
| Paywall design |
paywalls.md |
| Subscription metrics |
analytics.md |
| Testing & sandbox |
testing.md |
Core Rules
1. Choose Your Architecture
| Approach |
When to Use |
Tradeoff |
| Native only |
Single platform, full control |
More code, no cross-platform sync |
| RevenueCat/Adapty |
Cross-platform, fast launch |
1-2% fee, dependency |
| Hybrid |
Native + own backend |
Full control, more work |
2. Platform SDKs (Managed)
| Platform |
Pricing |
Best For |
| RevenueCat |
Free <$2.5k MTR, then 1% |
Most apps, best docs |
| Adapty |
Free <$10k MTR, then 0.6% |
Cost-conscious, A/B paywalls |
| Qonversion |
Free <$10k MTR, then 3% |
Simple setup |
| Superwall |
Paywall-focused |
Paywall A/B only |
| Glassfy |
Free <$10k, then 0.5% |
Budget option |
3. Product Types
| Type |
iOS |
Android |
Use Case |
| Consumable |
✅ |
✅ |
Credits, coins, lives |
| Non-consumable |
✅ |
✅ |
Unlock feature forever |
| Auto-renewable |
✅ |
✅ |
Subscriptions |
| Non-renewing |
✅ |
❌ |
Season pass, time-limited |
4. Server Verification is Non-Negotiable
Never trust client-side validation alone:
- iOS: App Store Server API with JWS verification
- Android: Google Play Developer API
- RevenueCat: Webhooks + REST API
5. Handle All Transaction States
| State |
Action |
| Purchased |
Verify → grant → finish |
| Pending |
Wait, show pending UI |
| Failed |
Show error, don't grant |
| Deferred |
Wait for parental approval |
| Refunded |
Revoke immediately |
| Grace period |
Limited access, prompt payment |
| Billing retry |
Maintain access during retry |
6. Subscription Lifecycle Events
Must handle all of these (native or via webhooks):
- INITIAL_PURCHASE → grant access
- RENEWAL → extend access
- CANCELLATION → mark will-expire
- EXPIRATION → revoke access
- BILLING_ISSUE → prompt to update payment
- GRACE_PERIOD → limited access window
- PRICE_INCREASE → consent required (iOS)
- REFUND → revoke + flag user
- UPGRADE/DOWNGRADE → prorate
7. Restore Purchases Always
Required by App Store guidelines:
- Prominent restore button
- Works for logged-out users
- Handles family sharing (iOS)
- Cross-device sync
8. Paywall Best Practices
See paywalls.md for detailed patterns:
- Show value before price
- Anchor pricing (3 options, highlight middle)
- Free trial prominent
- Social proof if available
- A/B test everything
9. Testing Strategy
| Environment |
iOS |
Android |
| Dev/Debug |
StoreKit Config file |
License testers |
| Sandbox |
Sandbox accounts |
Internal testing |
| Production |
Real accounts |
Production |
Sandbox subscription times:
- 1 week → 3 minutes
- 1 month → 5 minutes
- 1 year → 1 hour
10. App Store Guidelines
- No external payment links (anti-steering)
- Must use IAP for digital goods
- Physical goods/services can use Stripe
- Reader apps have exceptions
- 15-30% commission applies
Common Traps
- Testing with real money → use sandbox/test accounts
- Not finishing transactions → auto-refund (Android 3 days)
- Hardcoding prices → always fetch from store (regional pricing)
- Missing transaction observer → lose purchases made outside app
- No server verification → trivially bypassable
- Ignoring grace period → users churn when they could recover
- Poor paywall UX → kills conversion regardless of price
- Not tracking metrics → can't optimize what you don't measure
- Forgetting restore button → App Store rejection
- Not handling family sharing → confused users
1---2name: in-app-purchases3description: Implement in-app purchases and subscriptions across iOS, Android, and Flutter with RevenueCat, paywalls, receipt validation, and subscription analytics.4---56## When to Use78User needs to implement in-app purchases, subscriptions, paywalls, or monetization flows. Agent handles native APIs (StoreKit 2, Google Play Billing), cross-platform SDKs (RevenueCat, Adapty, Qonversion), paywall design, server verification, and subscription analytics.910## Quick Reference1112| Topic | File |13|-------|------|14| iOS StoreKit 2 | `storekit.md` |15| Android Billing | `google-play.md` |16| Flutter packages | `flutter.md` |17| RevenueCat SDK | `revenuecat.md` |18| Platform comparison | `platforms.md` |19| Server verification | `server.md` |20| Paywall design | `paywalls.md` |21| Subscription metrics | `analytics.md` |22| Testing & sandbox | `testing.md` |2324## Core Rules2526### 1. Choose Your Architecture27| Approach | When to Use | Tradeoff |28|----------|-------------|----------|29| Native only | Single platform, full control | More code, no cross-platform sync |30| RevenueCat/Adapty | Cross-platform, fast launch | 1-2% fee, dependency |31| Hybrid | Native + own backend | Full control, more work |3233### 2. Platform SDKs (Managed)34| Platform | Pricing | Best For |35|----------|---------|----------|36| RevenueCat | Free <$2.5k MTR, then 1% | Most apps, best docs |37| Adapty | Free <$10k MTR, then 0.6% | Cost-conscious, A/B paywalls |38| Qonversion | Free <$10k MTR, then 3% | Simple setup |39| Superwall | Paywall-focused | Paywall A/B only |40| Glassfy | Free <$10k, then 0.5% | Budget option |4142### 3. Product Types43| Type | iOS | Android | Use Case |44|------|-----|---------|----------|45| Consumable | ✅ | ✅ | Credits, coins, lives |46| Non-consumable | ✅ | ✅ | Unlock feature forever |47| Auto-renewable | ✅ | ✅ | Subscriptions |48| Non-renewing | ✅ | ❌ | Season pass, time-limited |4950### 4. Server Verification is Non-Negotiable51Never trust client-side validation alone:52- iOS: App Store Server API with JWS verification53- Android: Google Play Developer API54- RevenueCat: Webhooks + REST API5556### 5. Handle All Transaction States57| State | Action |58|-------|--------|59| Purchased | Verify → grant → finish |60| Pending | Wait, show pending UI |61| Failed | Show error, don't grant |62| Deferred | Wait for parental approval |63| Refunded | Revoke immediately |64| Grace period | Limited access, prompt payment |65| Billing retry | Maintain access during retry |6667### 6. Subscription Lifecycle Events68Must handle all of these (native or via webhooks):69- INITIAL_PURCHASE → grant access70- RENEWAL → extend access71- CANCELLATION → mark will-expire72- EXPIRATION → revoke access73- BILLING_ISSUE → prompt to update payment74- GRACE_PERIOD → limited access window75- PRICE_INCREASE → consent required (iOS)76- REFUND → revoke + flag user77- UPGRADE/DOWNGRADE → prorate7879### 7. Restore Purchases Always80Required by App Store guidelines:81- Prominent restore button82- Works for logged-out users83- Handles family sharing (iOS)84- Cross-device sync8586### 8. Paywall Best Practices87See `paywalls.md` for detailed patterns:88- Show value before price89- Anchor pricing (3 options, highlight middle)90- Free trial prominent91- Social proof if available92- A/B test everything9394### 9. Testing Strategy95| Environment | iOS | Android |96|-------------|-----|---------|97| Dev/Debug | StoreKit Config file | License testers |98| Sandbox | Sandbox accounts | Internal testing |99| Production | Real accounts | Production |100101Sandbox subscription times:102- 1 week → 3 minutes103- 1 month → 5 minutes104- 1 year → 1 hour105106### 10. App Store Guidelines107- No external payment links (anti-steering)108- Must use IAP for digital goods109- Physical goods/services can use Stripe110- Reader apps have exceptions111- 15-30% commission applies112113## Common Traps114115- Testing with real money → use sandbox/test accounts116- Not finishing transactions → auto-refund (Android 3 days)117- Hardcoding prices → always fetch from store (regional pricing)118- Missing transaction observer → lose purchases made outside app119- No server verification → trivially bypassable120- Ignoring grace period → users churn when they could recover121- Poor paywall UX → kills conversion regardless of price122- Not tracking metrics → can't optimize what you don't measure123- Forgetting restore button → App Store rejection124- Not handling family sharing → confused users
dvcrn