The Shelf / App Store / iOS Paywall Playbook
iOS Paywall Playbook
The paywall standard we ship on every app. Two rejections paid for it — you don't have to.
The job: put a compliant, converting paywall on an iOS subscription app — placements, structure, pricing presentation, StoreKit wiring — without re-deriving any of it or learning App Review's rules the expensive way.
Most paywall advice is a listicle. This is a working standard: the exact config we apply to every subscription app we ship, updated only when a test proves a winner or a reviewer proves us wrong. Both have happened. The file remembers.
What it does
Hand it to your agent and it builds or audits a paywall against the standard: the four-placement set (onboarding, session-start, action-gated, win-back), the one-clear-offer structure, honest pricing presentation with the per-week math and a correctly-computed savings badge, and the ten-item anti-pattern list. The audit greps run on any Swift codebase and come back with file:line findings.
The part that cost us
Two patterns the paywall-optimization world called canonical got a real app of ours rejected: the on-paywall free-trial toggle (Guideline 3.1.2(c)) and the post-cancel recovery sheet (Guideline 5.6 — even the fully-disclosed variant). Apple's reviewer language is quoted in the compliance reference, alongside the compliant replacements that got the resubmission through. Also in there: the full 12-item 3.1.2 disclosure checklist, including the subtle failure that gets apps bounced — legal links that exist but render too small and gray for a reviewer to find.
What's inside
SKILL.md— the playbook: placements, structure, pricing, benchmarks, StoreKit 2 patterns, audit greps, anti-patternsreferences/apple-compliance.md— both rejection case studies + the 3.1.2 checklistQUICKSTART.md— install for Claude Code, claude.ai, and Codex, with a first-run prompt- Field report on the product page — a real audit run, visible before you pay
Who it's for
Indie iOS devs and small teams shipping subscription apps. If your app gets downloads but no revenue, the leak is almost always placements or the paywall — this finds which.
Why not a free directory download
Free skill directories host thousands of unverified files nobody has run. This one has shipped real apps, eaten two real rejections, and gets updated when the evidence changes — the version number on the tag means something. Field-tested, documented, issued as-is.
FIELD REPORT real output, not a promise
Setup: the playbook's audit pass run against a shipped contract-review app in our own portfolio (anonymized). Placement-coverage greps first, then the compliance hard-ban check. This is the audit output format the skill produces — findings drawn from the real, documented audit.
Placement coverage
| Placement | Status | Evidence |
|---|---|---|
| Onboarding paywall | ✅ Present | Presented post-onboarding, before auth |
| Session-start | ❌ Missing | `rg 'scenePhase |
| Action-gated | ⚠️ Partial | Hard gates on export/compare existed; no free-first-action taste of the core feature. Changed to one free scan before the gate, with the paywall card copy updated to say so |
| Win-back (lapsed) | ❌ Missing | No App Store Connect win-back offers configured — flagged as a store-side task, not code |
Compliance hard-bans
- Post-cancel surface: the app auto-presented a "recovery" sheet when the user cancelled the native purchase sheet — fully disclosed (price, auto-renewal terms, legal links), which we then believed made it safe. A sibling app's rejection under Guideline 5.6 proved otherwise: the trigger is the violation, disclosure doesn't cure it. Removed; cancel now returns to the same paywall with nothing popped.
- Trial toggle: none present. ✅
- Billed-amount conspicuousness: annual price is the largest pricing element; trial stated subordinately with explicit "then $X automatically" language. ✅
Pricing presentation findings
- Savings badge computed in
Decimal— rendered "SAVE 0%" at runtime. The mock/screenshot mode hid it; only a live simulator run of the real paywall surfaced it. Recomputed inDoubleper the playbook formula; badge then rendered the true percentage. - Loss-aversion anchor was a bare struck-through price — relabeled "at weekly rate" (honest-label rule, avoids the 3.1.2 misleading-pricing read).
- CTA copy reframed from "7-Days free" to "1-Week free" (reads as one unit of the billing period, not a countdown).
Outcome
Four placement/compliance gaps and two pricing-presentation bugs found and fixed in one audit pass; the removed post-cancel sheet was the same pattern that had already caused a documented rejection elsewhere in the portfolio. Re-audited across subsequent builds: zero drift.
SERVICE RECORD living gear — updated as the factory learns
v1.0.0 — 2026-07-17
First issue. Ported from the factory's internal skill: sanitized for general use, methodology intact, field report captured from a real run.
Every update ships free to owners — your locker always serves the latest version.
QUESTIONS
Does this require a paywall SDK like Superwall or RevenueCat?›
No. The patterns are plain StoreKit 2 + SwiftUI. The methodology is mined from published Superwall material and our own shipped apps, but nothing here depends on any SDK.
Are the rejection case studies real?›
Yes. Both are documented rejections of an app in our own portfolio, with Apple's reviewer language quoted. The compliant replacements are what that app resubmitted with.
Will this work with claude.ai or Codex, not just Claude Code?›
Yes. It's plain markdown. The QUICKSTART covers install for Claude Code, claude.ai projects, and Codex/AGENTS.md setups.
Do the benchmarks guarantee my conversion rate?›
No, and we won't pretend otherwise. They're published reference points to judge whether your paywall needs work. The playbook fixes the config; your product does the rest.