paywall-upgrade-cro

# Paywall & Upgrade Screen CRO

Production-grade framework for in-product upgrade flows. Covers feature gate design, usage limit UX, trial expiration sequences, upgrade trigger timing, dark pattern avoidance, and ethical monetization. Distinct from public pricing pages (use page-cro for those) -- this focuses on in-product moments where users have already experienced value.

---

## Table of Contents

- [Initial Assessment](#initial-assessment)
- [The Value-First Principle](#the-value-first-principle)
- [Paywall Trigger Architecture](#paywall-trigger-architecture)
- [Paywall Screen Design](#paywall-screen-design)
- [Feature Gate Patterns](#feature-gate-patterns)
- [Usage Limit UX](#usage-limit-ux)
- [Trial Expiration Flows](#trial-expiration-flows)
- [Timing and Frequency Rules](#timing-and-frequency-rules)
- [Upgrade Flow Optimization](#upgrade-flow-optimization)
- [Dark Pattern Avoidance](#dark-pattern-avoidance)
- [Platform-Specific Considerations](#platform-specific-considerations)
- [Metrics and Benchmarks](#metrics-and-benchmarks)
- [A/B Test Framework](#ab-test-framework)
- [Output Artifacts](#output-artifacts)
- [Related Skills](#related-skills)

---

## Initial Assessment

### Required Context

| Question | Why It Matters |
|----------|---------------|
| What is the upgrade model? (freemium to paid, trial to paid, tier upgrade) | Determines the paywall type |
| What is free vs paid? | Defines the value gap to communicate |
| What triggers upgrade prompts today? | Identifies current trigger points |
| What is the current free-to-paid conversion rate? | Baseline for improvement |
| What is the aha moment for users? | Determines when the paywall should appear |
| What pricing model? (per seat, usage, flat) | Affects paywall messaging |
| Mobile app, web app, or both? | Platform-specific requirements |

---

## The Value-First Principle

The single most important rule in paywall design: **The user must have experienced real value before seeing an upgrade prompt.**

### Value-First Checklist

- [ ] User has completed the activation event (aha moment reached)
- [ ] User has used the product at least 2-3 times
- [ ] User has created or stored data they would lose
- [ ] The upgrade feels like a natural next step, not a trap

### When to Show vs When NOT to Show

| Show | Do Not Show |
|------|------------|
| After aha moment is reached | During onboarding |
| When user hits a genuine limit | On first login |
| When user clicks a paid feature | When user is in the middle of a task |
| After milestone completion | Immediately after a frustrating experience |
| On session start (gentle reminder) | After every action |

---

## Paywall Trigger Architecture

### Trigger Types

| Trigger | When It Fires | Best For |
|---------|--------------|----------|
| Feature gate | User clicks a locked feature | Feature-differentiated tiers |
| Usage limit | User reaches a quota | Usage-based pricing |
| Trial expiration | Trial period ending | Time-limited trial models |
| Time-based | After N days of active use | Freemium nurture |
| Milestone-based | After user achieves X | Upsell at success moments |
| Team-based | When team grows past free seat limit | Per-seat models |

### Trigger Priority Map

| User State | Primary Trigger | Timing |
|-----------|----------------|--------|
| Activated, under limits | Feature gate (when they try paid feature) | On click |
| Approaching limit | Soft warning (80% of limit) | Proactive |
| Hit limit | Usage limit paywall | On action that exceeds limit |
| Trial day 7 of 14 | Trial ending reminder | Session start |
| Trial day 13 of 14 | Urgent trial expiration | Session start + email |
| Trial day 14 | Trial expired | On login |
| Active for 30+ days, free | Value-based upgrade prompt | Session start, once per week |

---

## Paywall Screen Design

### Screen Anatomy

```
┌─────────────────────────────────────┐
│ [X Close / "Not now"]               │  Escape hatch (always visible)
│                                     │
│ HEADLINE: Value-focused             │  "Unlock [feature] to [benefit]"
│                                     │
│ [Feature preview / screenshot]      │  Show what they are missing
│                                     │
│ KEY BENEFITS:                       │
│ - Benefit 1                        │
│ - Benefit 2                        │
│ - Benefit 3                        │
│                                     │
│ PRICE: $X/month                    │  Clear, simple pricing
│ (or plan comparison)               │
│                                     │
│ [UPGRADE CTA - Primary]           │  "Start Pro Plan"
│ [Maybe Later - Secondary]          │  Clear secondary action
│                                     │
│ "Join 5,000+ teams on Pro"        │  Social proof
└─────────────────────────────────────┘
```

### Copy Patterns by Trigger Type

| Trigger | Headline Pattern | CTA Pattern |
|---------|-----------------|-------------|
| Feature gate | "Unlock [Feature] to [Benefit]" | "Upgrade to [Plan]" |
| Usage limit | "You've used all [N] [resources]" | "Get Unlimited [Resources]" |
| Trial expiring | "Your trial ends in [N] days" | "Continue with [Plan]" |
| Milestone | "You just hit [milestone]! Keep growing with Pro" | "Upgrade & Keep Growing" |
| Time-based | "[Product] Pro helps teams like yours [benefit]" | "See Pro Features" |

---

## Feature Gate Patterns

### Soft Gate (Preview + Lock)

User can see what the feature does but cannot use it fully.

```
┌──────────────────────────────┐
│  [Feature Preview]           │  Blurred screenshot or partial result
│                              │
│  [Lock Icon] Pro Feature     │
│                              │
│  [Feature name] lets you:    │
│  - Capability 1              │
│  - Capability 2              │
│                              │
│  [Upgrade to Pro - $X/mo]   │
│  [Maybe Later]              │
└──────────────────────────────┘
```

### Hard Gate (Block + Explain)

User cannot access the feature at a