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---5
6## When to Use
7
8User 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.
9
10## Quick Reference
11
12| 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` |
23
24## Core Rules
25
26### 1. Choose Your Architecture
27| 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 |
32
33### 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 |
41
42### 3. Product Types
43| 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 |
49
50### 4. Server Verification is Non-Negotiable
51Never trust client-side validation alone:
52- iOS: App Store Server API with JWS verification
53- Android: Google Play Developer API
54- RevenueCat: Webhooks + REST API
55
56### 5. Handle All Transaction States
57| 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 |
66
67### 6. Subscription Lifecycle Events
68Must handle all of these (native or via webhooks):
69- INITIAL_PURCHASE → grant access
70- RENEWAL → extend access
71- CANCELLATION → mark will-expire
72- EXPIRATION → revoke access
73- BILLING_ISSUE → prompt to update payment
74- GRACE_PERIOD → limited access window
75- PRICE_INCREASE → consent required (iOS)
76- REFUND → revoke + flag user
77- UPGRADE/DOWNGRADE → prorate
78
79### 7. Restore Purchases Always
80Required by App Store guidelines:
81- Prominent restore button
82- Works for logged-out users
83- Handles family sharing (iOS)
84- Cross-device sync
85
86### 8. Paywall Best Practices
87See `paywalls.md` for detailed patterns:
88- Show value before price
89- Anchor pricing (3 options, highlight middle)
90- Free trial prominent
91- Social proof if available
92- A/B test everything
93
94### 9. Testing Strategy
95| Environment | iOS | Android |
96|-------------|-----|---------|
97| Dev/Debug | StoreKit Config file | License testers |
98| Sandbox | Sandbox accounts | Internal testing |
99| Production | Real accounts | Production |
100
101Sandbox subscription times:
102- 1 week → 3 minutes
103- 1 month → 5 minutes
104- 1 year → 1 hour
105
106### 10. App Store Guidelines
107- No external payment links (anti-steering)
108- Must use IAP for digital goods
109- Physical goods/services can use Stripe
110- Reader apps have exceptions
111- 15-30% commission applies
112
113## Common Traps
114
115- Testing with real money → use sandbox/test accounts
116- 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 app
119- No server verification → trivially bypassable
120- Ignoring grace period → users churn when they could recover
121- Poor paywall UX → kills conversion regardless of price
122- Not tracking metrics → can't optimize what you don't measure
123- Forgetting restore button → App Store rejection
124- Not handling family sharing → confused users
modbender