# Upgrade Paths

> Convert free to paid in-product: feature gates, upgrade screens, trial-end moments and expansion offers. Use when designing in-app paywalls, upgrade modals, or usage triggers.

- Skill: `poorvith-mp/upgrade-paths` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add poorvith-mp/upgrade-paths`
- Raw SKILL.md: https://api.skillmd.com/api/skills/poorvith-mp/upgrade-paths/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: poorvith-mp (https://skillmd.com/u/poorvith-mp)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/poorvith-mp/upgrade-paths

---


# upgrade-paths

## Core Philosophy
Freemium and free trial tiers fail when the upgrade path is invisible, arbitrary, or punitive. The best software upgrades do not feel like an aggressive tollbooth; they feel like a natural, celebrated milestone of business growth. Effective upgrade paths align monetization with the exact moment a customer realizes enterprise scale, mission-critical operational reliance, or collaborative team expansion.

---

## 4-Step Upgrade Path Engineering

### Step 1: Monetization Trigger & Gate Classification
1. **The 3 Upgrade Trigger Archetypes**:
   - *Capacity & Usage Limits (Scale Trigger)*:
     - Free tier covers individual/hobbyist volume (e.g. 10,000 monthly events, 5GB storage).
     - Upgrade triggers when volume indicates real commercial production usage.
   - *Collaboration & Team Gates (Organizational Trigger)*:
     - Product is free for 1 user; adding teammate #2 or #3 requires upgrading to Team Plan.
     - Role-based permissions (RBAC), shared workspaces, and centralized billing.
   - *Enterprise Governance & Security Gates (Compliance Trigger)*:
     - SAML SSO (Okta, Azure AD), audit logs, custom data retention, dedicated VPC peering, and 99.99% uptime SLAs.

### Step 2: In-Product Paywall & Upgrade UX
1. **Contextual Upgrade Modals**:
   - Never show a generic "Upgrade Now" screen. The modal must explicitly state *why* it is being triggered:
     - Example: *"You've reached your free limit of 10,000 events this month. Upgrade to Pro to ensure zero dropped events."*
2. **Feature Gate Interaction Modes**:
   - *Soft Gates (Preview & Unlock)*: Let the user explore the UI of the premium feature (e.g. custom dashboards), but show a clear upgrade banner when they click "Save" or "Apply".
   - *Hard Gates (Access Blocked)*: Completely lock enterprise-only settings (e.g. SSO configuration) with a direct "Request Enterprise Access" flow.
3. **1-Click Self-Serve Checkout**:
   - Integrate Stripe Elements directly into the modal; never force users to leave their current workflow or re-enter billing details if already on file.

### Step 3: Trial-to-Paid Expiration Sequences
1. **The 14-Day Trial Touchpoint Schedule**:
   - *Day 0*: Welcome & Guided "Aha!" setup checklist.
   - *Day 3*: Value realization check (did they activate core feature?).
   - *Day 7*: Mid-trial usage report ("Your team has processed 14,000 records so far").
   - *Day 11 (3 Days Left)*: Urgency notice: "Your trial ends in 72 hours. Add payment to prevent workflow pause."
   - *Day 14 (Trial End)*: Graceful transition.
2. **Soft Downgrade Policy**:
   - When a trial expires without payment, never delete user data immediately. Automatically downgrade them to the Free/Read-Only tier and preserve their workspace for 30 days.

### Step 4: Expansion & Usage Alerts
1. **Proactive Capacity Warnings**:
   - Send automated in-app and email alerts at **80%** and **95%** usage thresholds:
     - *"You are at 85% of your monthly API quota. Upgrade now or enable automatic overage protection."*
2. **Expansion Plays for Existing Customers**:
   - Identify accounts approaching seat or compute thresholds and trigger automated account executive outreach for custom annual contracts.

---

## Deliverable Format: Upgrade Architecture Specification (`UPGRADE-PATHS-SPEC.md`)

```markdown
# Upgrade Path Architecture & Paywall Specification: [Product Name]

## 1. Value Metric & Gate Taxonomy
| Feature / Tier Gate | Free / Starter | Pro ($[X]/mo) | Enterprise (Custom) |
|---|---|---|---|
| Monthly Events | 10,000 | 250,000 | Custom / Unlimited |
| Team Members | 1 seat | Up to 10 seats | Unlimited |
| SSO (SAML/Okta) | No | No | Included |
| Audit Logs | 7-day retention | 30-day retention | 365-day retention |

## 2. In-Product Paywall UX Specs
- **Trigger**: User invites 2nd team member on Free Plan.
- **Headline**: *"Collaborate with your team in real time"*
- **Body Copy**: *"Free plans include 1 workspace seat. Upgrade to the Team Plan to invite colleagues, share templates, and assign granular permissions."*
- **CTA Button**: `[Upgrade to Team - $29/mo]` (Instant 1-click modal checkout)
- **Secondary CTA**: `[Learn more about Team features]`

## 3. Quota Notification Matrix
| Threshold | Channel | Timing | Copy Hook |
|---|---|---|---|
| 80% Usage | In-App Toast | Real-time | "Approaching free limit (80% used)" |
| 95% Usage | Email + Banner | Real-time | "Action needed: 500 events remaining" |
| 100% Usage | Modal Gate | Immediate | "Limit reached - Upgrade to keep processing" |

## 4. Post-Trial Soft Downgrade Policy
- **Grace Period**: 7 days read-only access.
- **Data Retention**: All projects and configurations preserved for 60 days.
```

---

## Worked Example: Cloud Developer Tool Upgrade Flow

- **Trigger**: Developer reaches 5 active environments on the free tier and attempts to spin up a 6th.
- **Modal Display**: Shows an interactive cost slider demonstrating that upgrading to Pro allows 25 environments for $40/month, saving $120/month compared to raw cloud hosting.
- **Result**: Conversion rate on environment creation paywall hit 19.4%, generating $14,000 in incremental MRR in the first 45 days.

---

## Verification Checklist

- [ ] Upgrade gates align with real business growth milestones (seats, volume, security).
- [ ] Paywall modals clearly articulate the specific context and value of the locked feature.
- [ ] Self-serve 1-click upgrade checkout takes $< 30$ seconds.
- [ ] Automated warning notifications fire at 80% and 95% capacity.
- [ ] Trial expirations gracefully soft-downgrade to free/read-only with data preserved.

---

## Anti-Patterns

- **Hostage Paywalls**: Locking users out of viewing or exporting data they created on the free tier.
- **Mysterious Upgrades**: Showing a generic "Contact Sales to Upgrade" modal for a standard $20/month SaaS feature.
- **Premature Gating**: Gating the core value proposition so aggressively that users never reach the initial "Aha!" moment.