Monetization & Entitlements Master PRD

Prepared 18 July 2026 · product requirements normalized from the placement artifact, current implementation status, and founder requirements

Problem and objective

The app has billing transport, access projection, and several paywall surfaces, but plan limits remain provisional, backend enforcement is absent, legacy and new tier stores overlap, and the requested offers/trial/grandfathering are not implemented. The objective is one auditable entitlement system shared by App Store Connect, RevenueCat, backend, iOS, and admin.

Product principles

• Backend access and quota decisions are authoritative; iOS explains and resumes intent.
• Explore remains discoverable to Free users; limits affect playback time, not catalog visibility.
• A paywall appears at a clear value moment, never randomly over playback or another modal.
• Displayed discounts must map to a real store product/offer and actual eligibility.
• Grandfathered access is independent from App Store purchase state.
• No user can lose paid Pro because a lower complimentary grant is applied.
• Every quota has a named window, rollover rule, cap, and immutable usage ledger.

Plan contract

Rollover normalization

Three-day Plus trial

• Trial attaches to selected Plus subscription products as an Apple introductory free trial.
• Trial begins only after the user confirms the App Store purchase sheet; merely viewing a paywall never starts it.
• Backend detects RevenueCat period_type=TRIAL, sets access phase trial, trial start/end, and the restricted trial limit profile.
• Trial receives Plus capabilities, but recurring-show generation is capped at one show for the weekly window and one total during the three-day trial, and one-time episodes are capped at four total during the trial.
• Renewal price, billing cadence, and exact trial end are displayed beside the CTA.
• Trial reminder is opt-in, scheduled after notification permission, and canceled/rescheduled if the entitlement changes.
• Apple permits only one introductory offer per subscription group; a user who consumes this trial cannot receive another intro offer in that group.

Offer ladder and state machine

Recommended offer mechanics

For never-subscribed users, promotional offers are not the right primitive because Apple limits them to current or previous subscribers. Use App Store introductory pricing on dedicated rescue products/packages, or approved offer codes. Attach every rescue product to the same Plus entitlement and show only through its RevenueCat offering. For lapsed subscribers, use promotional or win-back offers instead. Discount means 50%/65% off the first paid billing period unless product signs off on another duration; renewal returns to the standard price.

Paywall placements

Subscription management

Profile/Settings → Plan & Billing becomes the permanent self-service entry point. It shows the effective plan, trial/paid/complimentary state, renewal or expiry date, current weekly and one-time balances, pending plan changes, Restore Purchases, and a Change or Manage Subscription action. Free and grandfathered-only users open the plan comparison flow; App Store subscribers open Apple’s native management sheet or RevenueCat Customer Center. Upgrades, downgrades, cadence changes, cancellation, and restore must refresh the server-authoritative access snapshot. The complete iOS build specification is in the separate iOS Subscription Management IPRD.

In-app jump notifications / monetization nudges

A jump notification is defined here as an in-app banner, card, coachmark, or inbox item that opens a paywall after an explicit tap. It must not automatically interrupt active playback.

• Eligible moments: 80% allowance used, weekly credit available, trial ending in 24 hours, locked feature discovery, newly available rollover credit, and a campaign-qualified 50%/65% offer.
• Maximum one monetization nudge per session, one push per 72 hours, and no nudge within 24 hours of a paywall dismissal.
• Suppress during playback, creation submission, onboarding before the offer step, another sheet, reauthentication, or a purchase in progress.
• Stop all acquisition nudges for active trial, paid, or grandfathered users.
• Persist exposures server-side for cross-device frequency caps.

Grandfathering

Admin selects a cohort using signup cutoff plus optional filters, chooses Plus or Pro, start/end time, campaign, reason, and whether the grant is revocable. The backend creates idempotent grants in bulk after a dry run. A grant overlays store access but never lowers a paid tier. Expiry reveals the underlying store tier. Lifetime access requires a nullable expiry or explicit permanent-grant type; do not fake lifetime with a distant date.

Analytics and success metrics

• Events: gate evaluated, paywall impression/close, exit offer impression, CTA, purchase started/completed/failed, restore, activation latency, trial started/converted/canceled, quota reserved/finalized/released, nudge impression/tap/dismiss, grant created/revoked/expired.
• Dimensions: placement, offer stage, offering/product, tier, access phase, quota type, remaining allowance, app build, environment, cohort, experiment.
• Primary metrics: paid conversion, trial start, trial-to-paid conversion, realized LTV, restore success, entitlement mismatch, gate-to-purchase conversion, refund rate, and negative UX signals.

Master acceptance criteria

• One canonical Free/Plus/Pro access snapshot is used by backend, iOS, and admin.
• Every paid capability is blocked by the backend as well as explained by iOS.
• Every quota returns remaining, reset time, rollover balance, and authoritative denial reason.
• A sandbox purchase projects through RevenueCat webhook and unlocks within the agreed latency.
• Trial users receive the trial-specific limit profile and convert/expire correctly.
• Offer-stage state survives reinstall and works across devices.
• Grandfathering dry-run, apply, revoke, expire, and paid-tier overlay are audited.
• No paywall appears over another sheet or active purchase; every successful purchase resumes the initiating action exactly once.