Separate iOS build specification

iOS Subscription Management IPRD

Prepared 18 July 2026 · companion to the Monetization & Entitlements Master PRD

Decision

Add a permanent Profile/Settings → Plan & Billing destination. Version 1 should use Apple’s native subscription-management sheet for active App Store subscribers and the existing RevenueCat plan comparison/paywall for Free users. RevenueCat Customer Center is the branded upgrade path if the current RevenueCat plan supports it.

Objective and scope

Give every user one trustworthy place to understand their effective plan, usage, renewal or expiry, and subscription actions. This IPRD covers navigation, screen states, upgrades, downgrades, billing-cadence changes, cancellation handoff, restore, complimentary access, delayed backend activation, analytics, and QA. It does not redesign the acquisition paywall or admin grandfathering.

Entry points and navigation

Profile tab → Settings → Plan & Billing.
Optional direct row on Profile beneath account identity for higher discoverability.
Trial-ending and billing-issue nudges deep-link to the same destination.
Paywall Restore and subscription-status links return to this screen after completion.
Use the established iOS pattern: NavigationStack with a semantic grouped List, system colors, SF Symbols by name, Dynamic Type, and VoiceOver labels.

Plan & billing states

User state	Primary information	Primary action	Secondary actions
Free	Free plan; 1 recurring credit/week; 3 one-time credits/3 days; next resets	View Plus & Pro	Restore Purchases
Plus trial	Plus trial; exact end/renewal; 1 recurring credit maximum during trial	Manage Subscription	Compare Pro, Restore, trial reminder
Paid Plus	Product cadence, renewal date/price, 2 recurring credits/week	Change or Manage Plan	Upgrade to Pro, Restore
Paid Pro	Product cadence, renewal date/price, 5 recurring credits/week	Change or Manage Plan	Restore
Canceled but active	Access remains until expiry; renewal off	Manage / Resubscribe	Restore
Grace or billing retry	Billing issue without overstating loss of access	Fix Payment / Manage	Help
Grandfathered only	Complimentary Plus/Pro, campaign reason where appropriate, exact expiry/permanent	View paid plans	Contact support
Paid + grandfathered	Effective higher plan and both access sources	Manage store subscription	View complimentary expiry
Pending plan change	Current plan plus “changes to X on [date]”	Manage Subscription	Refresh status

Screen requirements

Plan & Billing overview

Current plan badge: Free, Plus trial, Plus, Pro, or Complimentary Plus/Pro.
Status line: renews, expires, canceled-active, billing retry, grace, or permanent grant.
Localized price and billing cadence only from StoreKit/RevenueCat; never hardcode currency.
Usage cards: recurring credits and weekly reset, one-time credits and reset, Explore time, files, and tier capabilities.
Pending-change banner with destination plan and effective date.
Actions: View Plans, Change/Manage Subscription, Restore Purchases, Billing Help, Terms, Privacy.

Plan comparison for Free or complimentary-only users

Reuse the standard plan comparison product data and current eligible offering.
Do not run the acquisition exit-offer ladder from a voluntary Settings visit unless the backend explicitly marks the placement eligible.
After purchase, wait for access activation and return to the overview with the new plan.

Change and management flows

User opens Plan & Billing; iOS refreshes server access and RevenueCat customer information.
Free user taps View Plans and receives the plan comparison/purchase flow.
Active App Store subscriber taps Change or Manage Subscription.
Version 1 presents Apple’s native manage-subscriptions sheet. If RevenueCat Customer Center is adopted, present its Change Plans path instead.
User confirms upgrade, downgrade, crossgrade, cadence change, cancellation, or no change in Apple UI.
On sheet dismissal and next foreground, refresh RevenueCat and backend. Show pending state if the change is scheduled.
Only the backend’s effective access response changes feature gates. Never infer the tier merely because the management sheet closed.

Upgrade and downgrade timing

Change	Expected Apple behavior	App behavior
Plus → Pro upgrade	Normally immediate with prorated handling	Show activating state, then unlock Pro only after confirmed active entitlement
Pro → Plus downgrade	Normally effective next renewal	Keep Pro until effective date and show scheduled Plus
Same-tier, same-duration crossgrade	Normally immediate	Refresh product/cadence and preserve the correct quota window
Different-duration crossgrade	Normally next renewal	Show pending cadence and keep current product until effective
Cancel auto-renew	Access continues through paid expiry	Show canceled-active; do not downgrade early
Upgrade during free trial	May temporarily produce two active products in the group	Resolve highest effective tier, deduplicate quota grants, and test explicitly

Recommended implementation

Version 1 — recommended

Native SwiftUI manageSubscriptionsSheet or StoreKit manage sheet. Lowest dependency, Apple-owned change/cancel UI.

Version 2 — optional

RevenueCat Customer Center for branded plan changes, cancel/refund paths, restore, support, and retention prompts.

Fallback

RevenueCat managementURL when native presentation is unavailable or the original purchase belongs to another supported store.

Confirm all Plus/Pro products share one subscription group.
Rank Pro above Plus; configure cadence products and eligible change paths intentionally.
If Customer Center is chosen, verify RevenueCat plan access and supported SDK, then configure allowed products per current product.
Use server-controlled feature flag to select native management or Customer Center.

Backend and RevenueCat contract

Access response includes effective plan/phase, source, product ID, cadence, renewal/expiry, auto-renew, trial, grace/billing-retry, and pending plan/effective date.
PRODUCT_CHANGE is informative and must not itself change effective access.
Actual upgrade/downgrade follows confirmed active transaction or renewal projection.
Plan changes do not double-credit weekly or monthly quota windows; use immutable ledger and plan-version transition entries.
Highest effective access wins across paid, trial, and complimentary sources.
Restore and post-management refresh are idempotent and safe across devices.

Error and edge states

Offline: show cached status with “Last updated” and disable mutation actions except retry.
No active App Store subscription: return to View Plans and Restore; do not show an empty management sheet.
Delayed webhook: show “Confirming your plan change” and poll with bounded retry.
Nothing to restore: provide a calm result and support route.
Different Apple ID or transferred purchase: explain the mismatch without exposing account details.
Grandfathered user cannot cancel complimentary access through Apple; label it separately.
Refund/revocation: refresh immediately and explain current effective access.
Multiple entitlement records: choose the highest active tier and alert backend reconciliation.

Analytics

Track Plan & Billing opened with tier, phase, source, and entry point.
Track View Plans, Manage, Restore, Help, management-sheet presented/dismissed, and refresh result.
Track requested/observed upgrade, downgrade, crossgrade, cancel, resubscribe, and pending-change completion.
Never log Apple ID, full transaction payload, or payment details.
Measure successful self-service completion, activation latency, restore success, support deflection, and plan-change mismatch rate.

Acceptance and QA checklist

Every state in the matrix has a deterministic StoreKit/backend fixture and screenshot.
Free, trial, Plus, Pro, canceled-active, grace, grandfathered, paid+grant, and pending-change states render correctly.
Plus→Pro unlocks only after effective confirmation; Pro→Plus remains Pro until the scheduled date.
Weekly quotas remain Free 1, trial 1 total, Plus 2, Pro 5 across product changes.
Free one-time quota remains 3 per 3-day window across upgrade, expiry, and restore.
Cancel never removes access early; restore never creates duplicate quota.
Sheet dismissal with no change leaves state untouched.
VoiceOver, Dynamic Type, Reduce Motion, localization, small/large iPhone, iPad, dark mode, offline, and delayed activation pass.
Terms, Privacy, Restore, and Billing Help are always reachable.