Skills
skills/borghei/claude-skills/paywall-upgrade-cro

paywall-upgrade-cro

Originally fromcoreyhaines31/marketingskills
Installation
SKILL.md

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

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 all. Show the value clearly.

┌──────────────────────────────┐
│  [Lock Icon]                 │
│                              │
│  This feature is available   │
│  on the Pro plan             │
│                              │
│  What you get:               │
│  - Benefit 1                 │
│  - Benefit 2                 │
│  - Benefit 3                 │
│                              │
│  [Upgrade to Pro]            │
│  [Compare Plans]             │
└──────────────────────────────┘

Feature Gate Design Rules

  • Always explain WHY the feature is valuable (not just that it is locked)
  • Show what the feature produces (output preview) when possible
  • Include a "Compare Plans" link for users who want more detail
  • Do not gate features the user was already using during trial

Usage Limit UX

Approaching Limit (80% Warning)

┌──────────────────────────────────┐
│  [Progress Bar: 80%]            │
│  You've used 80 of 100 credits  │
│                                  │
│  [Get More Credits]  [Dismiss]  │
└──────────────────────────────────┘

At Limit (100%)

┌──────────────────────────────────────┐
│  [Progress Bar: 100%]               │
│  You've reached your monthly limit  │
│                                      │
│  Free: 100 credits | Pro: Unlimited │
│                                      │
│  [Upgrade to Pro]                   │
│  [Delete items to free space]       │  Alternative action
└──────────────────────────────────────┘

Usage Limit Rules

  • Show usage context before the limit hits (progress indicators in the UI)
  • Provide an alternative action (delete, archive, export) when possible
  • Never delete user data when limits are reached
  • Allow grace period (do not cut off mid-task)

Trial Expiration Flows

Trial Countdown Sequence

Day Channel Message Tone
Day 7 (of 14) In-app banner "7 days left in your trial" Informational
Day 10 Email "4 days left -- here's what you've accomplished" Value summary
Day 12 In-app modal "2 days left -- don't lose access to [feature]" Mild urgency
Day 13 Email "Tomorrow is your last day" Urgency + offer
Day 14 In-app full screen "Your trial has ended" Clear options
Day 15 Email "We kept your data safe -- reactivate anytime" Reassurance

Trial Expiration Screen Design

┌─────────────────────────────────────────┐
│  Your trial has ended                    │
│                                          │
│  What you accomplished during trial:     │
│  - Created [N] projects                 │  Personalized data
│  - Invited [N] team members             │
│  - Saved an estimated [X] hours         │
│                                          │
│  What happens now:                       │
│  - Your data is saved for 30 days       │
│  - Read-only access to existing work    │
│  - Full access resumes when you upgrade │
│                                          │
│  [Continue with Pro - $X/mo]            │
│  [Remind Me Later]  [Downgrade to Free] │
└─────────────────────────────────────────┘

Timing and Frequency Rules

Frequency Caps

Rule Implementation
Max 1 paywall per session Do not interrupt twice in one visit
3-7 day cooldown after dismissal If they click "Not now", wait at least 3 days
Never during active task If user is creating, editing, or mid-workflow, do not interrupt
Cap at 3 per month After 3 dismissals in a month, stop showing until next month
Track annoyance signals If user closes paywall within 1 second repeatedly, increase cooldown

Escalation Pattern

Attempt Approach Invasiveness
1 Subtle banner or sidebar widget Low
2 Modal with value proposition Medium
3 Modal with special offer (discount/extended trial) Medium-High
4+ Reduce frequency, switch to email nurture Low (change channel)

Upgrade Flow Optimization

From Paywall Click to Payment

Step Optimization
1. Click upgrade CTA Opens upgrade flow (do not redirect to external page if avoidable)
2. Plan selection Pre-select the recommended plan, show comparison
3. Payment Pre-fill known info (email, name), support all payment methods
4. Confirmation Immediate access to paid features, confirmation email
5. Post-upgrade Guide to newly unlocked features, celebration moment

Friction Reduction

  • Keep the upgrade flow in-context (modal or slide-out, not a full page redirect)
  • Pre-fill all known information
  • Support saved payment methods and one-click upgrade for returning upgraders
  • Show price clearly before the payment step (no surprise charges)

Dark Pattern Avoidance

Patterns to NEVER Use

Dark Pattern Why It Fails Ethical Alternative
Hidden close button Breaks trust, generates support tickets Clear X in top-right corner
Shame copy ("No, I don't want to grow my business") Manipulative, reduces brand respect "Maybe later" or "Not now"
Countdown timer (fake urgency) Users discover it resets, destroys credibility Only use for genuinely expiring offers
Confusing plan selection Users feel tricked, higher refund rate Clear plan names with honest comparison
Blocking critical actions Users feel trapped, generates churn Allow continued use of existing features
Making downgrade difficult Regulatory risk (especially in EU/CA) One-click downgrade option

Platform-Specific Considerations

iOS App Store

  • Apple requires in-app purchase (IAP) for digital goods/services
  • Apple takes 30% commission (15% for small business program)
  • Must comply with App Store Review Guidelines 3.1
  • Cannot link to external payment pages from within the app
  • Must clearly communicate subscription terms and renewal

Google Play

  • Similar IAP requirements as iOS
  • Google Play billing required for digital goods
  • 15% commission on first $1M in annual revenue, then 30%
  • Must provide clear subscription management

Web App

  • Full control over payment flow and presentation
  • Can offer any payment method
  • No platform commission
  • Can A/B test freely without app review delays

Metrics and Benchmarks

Key Metrics

Metric Formula Benchmark
Paywall impression rate Users who see paywall / Active users Track, no universal benchmark
Paywall CTR Upgrade clicks / Paywall impressions 5-15%
Upgrade completion rate Completed upgrades / Upgrade clicks 30-60%
Free-to-paid conversion Paid users / Total free users 2-5% for freemium, 15-30% for trial
Revenue per user (ARPU) Total revenue / Active users Segment-dependent
Post-upgrade churn (30-day) Churned within 30 days / New paid users < 10%

Warning Signals

Signal Diagnosis Action
CTR < 3% Paywall copy or timing is wrong Test different triggers and messaging
Completion < 20% Upgrade flow has too much friction Simplify payment flow
Post-upgrade churn > 15% Value not matching expectations Review feature access and onboarding
Free-to-paid < 1% Paywall appears before value is delivered Delay triggers until after activation

A/B Test Framework

High-Impact Tests

Test Hypothesis Metric
Trigger timing (earlier vs later) Later trigger = higher conversion rate Free-to-paid conversion
Soft gate vs hard gate Soft gate (preview) converts better Feature gate CTR
Copy variation Value-focused vs urgency-focused Paywall CTR
Price presentation Monthly vs annual default ARPU

Test Measurement

  • Run for minimum 2 weeks or 100 conversions per variant
  • Track upgrade rate AND 30-day post-upgrade retention
  • A test that increases upgrades but increases churn is a net negative

Output Artifacts

Artifact Format Description
Paywall Trigger Map Trigger x timing x frequency table All trigger points with rules and cooldowns
Screen Copy Set Complete screen designs Headline, benefits, CTA, escape hatch for each paywall type
Upgrade Flow Diagram Step-by-step flow Paywall click to post-upgrade confirmation
Dark Pattern Audit Checklist Review of existing paywall for manipulative patterns
Trial Expiration Sequence Day-by-day plan In-app + email sequence for trial countdown
A/B Test Backlog Prioritized table Test ideas ranked by expected impact

Tool Reference

1. paywall_trigger_auditor.py

Audits paywall trigger configuration for timing, frequency, and coverage issues. Reads a JSON file of trigger rules and user event data, then flags misconfigured triggers, missing cooldowns, and dark-pattern risks.

python scripts/paywall_trigger_auditor.py triggers.json --format text
python scripts/paywall_trigger_auditor.py triggers.json --format json
Flag Type Description
triggers.json positional Path to JSON file with trigger rules and event data
--format optional Output format: text (default) or json

2. upgrade_funnel_analyzer.py

Analyzes upgrade funnel step-by-step conversion from paywall impression through payment completion. Identifies the highest-drop steps, calculates stage-over-stage conversion, and benchmarks against industry targets.

python scripts/upgrade_funnel_analyzer.py funnel.json --format text
python scripts/upgrade_funnel_analyzer.py funnel.json --format json
Flag Type Description
funnel.json positional Path to JSON file with funnel step data
--format optional Output format: text (default) or json

3. paywall_copy_scorer.py

Scores paywall screen copy against proven conversion patterns. Evaluates headline structure, benefit clarity, CTA strength, social proof presence, and dark-pattern risk. Outputs a 0-100 score with itemized feedback.

python scripts/paywall_copy_scorer.py copy.json --format text
python scripts/paywall_copy_scorer.py copy.json --format json
Flag Type Description
copy.json positional Path to JSON file with paywall copy elements
--format optional Output format: text (default) or json

Troubleshooting

Problem Likely Cause Resolution
Paywall CTR below 3% Trigger fires before user reaches aha moment or copy is feature-focused instead of benefit-focused Delay trigger until after activation event; rewrite headline to outcome-based messaging (lifts CTR up to 23% per Strava case study)
Upgrade completion below 20% Too much friction in payment flow (redirects, missing payment methods, surprise charges) Keep flow in-context (modal/slide-out), pre-fill known info, show price before payment step
Post-upgrade churn above 15% Value expectation mismatch -- paid experience does not match what the paywall promised Audit feature access post-upgrade, add guided tour of newly unlocked features, align copy with actual capabilities
Free-to-paid conversion below 1% Paywall appears before value is delivered or free tier is too generous Map activation events and ensure paywall only fires after aha moment; review free vs paid feature boundary
Users close paywall within 1 second repeatedly Paywall is interrupting workflow or appearing too frequently Increase cooldown to 7+ days after dismissal, cap at 3 per month, switch to less intrusive format (banner vs modal)
Mobile paywall underperforms desktop by >30% iOS/Android IAP friction, small dismiss targets, or full-screen overlay on mobile Ensure 44x44px touch targets, use bottom-sheet format on mobile, comply with App Store guidelines
Trial expiration emails have low open rate Generic subject lines, wrong send timing, or email deliverability issues Personalize with usage data ("You created 12 projects"), send at user's active hours, check spam score

Success Criteria

  • Free-to-paid conversion rate reaches 2-5% for freemium models or 15-30% for trial models within 90 days of optimization
  • Paywall CTR stabilizes at 5-15% across all trigger types
  • Upgrade completion rate (paywall click to payment) exceeds 30%
  • Post-upgrade 30-day retention exceeds 90% (churn below 10%)
  • Paywall annoyance signals (sub-1-second dismissals) decrease to below 5% of impressions
  • Zero dark patterns present in paywall audit (no shame copy, no hidden close buttons, no fake urgency)
  • Annual plan adoption reaches 40%+ of new upgrades when annual toggle defaults are implemented (benchmark: 20-40% lift)

Scope & Limitations

In scope: In-product upgrade flows including feature gates, usage limit screens, trial expiration sequences, upgrade trigger timing, save offer strategy, paywall screen design, and A/B test frameworks for freemium-to-paid and trial-to-paid conversion.

Out of scope: Public-facing pricing pages (use page-cro), the pricing model itself (use pricing-strategy), post-signup onboarding before the aha moment (use onboarding-cro), initial registration flows (use signup-flow-cro), and post-upgrade churn intervention (use churn-prevention). This skill does not cover App Store Optimization (ASO) or paid acquisition strategies. Scripts operate on local data only -- no integrations with payment processors, analytics platforms, or A/B testing tools.

Limitations: Conversion benchmarks are based on aggregate SaaS/app industry data and may vary significantly by vertical, price point, and audience. Mobile paywall performance is highly dependent on platform-specific IAP requirements (Apple 30% commission, Google Play billing). Scripts analyze static snapshots; real-time paywall optimization requires integration with analytics and experimentation platforms not provided here.

Integration Points

  • pricing-strategy -- Feed pricing tier structure and value metric into paywall copy and plan comparison design
  • onboarding-cro -- Coordinate activation event definitions; paywall triggers should fire only after onboarding confirms aha moment
  • churn-prevention -- Post-upgrade churn data feeds back into paywall expectation-setting; save offers should align with churn prevention playbook
  • page-cro -- Public pricing page design feeds into in-app upgrade flow consistency; ensure messaging alignment
  • signup-flow-cro -- Registration flow completion triggers trial start; trial duration and paywall timing depend on signup context
  • popup-cro -- Share frequency capping logic and suppression rules; paywall modals follow same UX principles as marketing popups

Related Skills

  • page-cro -- Use for public pricing page optimization. Paywall-upgrade-cro handles in-product upgrade moments.
  • onboarding-cro -- Use when users have not reached activation. Do not show paywalls before the aha moment.
  • pricing-strategy -- Use when the pricing model itself needs redesigning (tier structure, value metric, price points).
  • churn-prevention -- Use when users upgrade but then churn. If they never upgrade, the problem is here.
  • signup-flow-cro -- Use for the initial registration flow. Paywall-upgrade-cro handles post-signup monetization.
Weekly Installs
50
Repository
borghei/claude-skills
GitHub Stars
103
First Seen
3 days ago
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykPass