RevenueCat Paywall Implementation: Getting Started (Part 1)

Building a paywall is one of the most critical steps in monetizing your app. Get it wrong, and you leave revenue on the table. Get it right, and your paywall becomes your most important business asset. This tutorial walks you through the foundational steps of implementing a RevenueCat Paywall — from installing the SDK to choosing the monetization strategy that fits your app.

Introduction to RevenueCat Paywalls

RevenueCat's paywall system gives developers a flexible, remotely configurable way to present subscription offers to users. RevenueCat Paywalls are included as part of the RevenueCatUI package in the RevenueCat SDK — meaning you don't need a separate paywall library to get started.

There are currently two paywall systems available:

• The new Paywall Builder — the recommended approach for all new implementations. It provides a visual, no-code editor in the RevenueCat dashboard to design and iterate on paywalls without app store resubmissions.
• The legacy paywall system (paywalls-legacy) — still supported, but new projects should use the new paywall builder. Legacy paywall documentation is available here.

This tutorial focuses on the new Paywall Builder while also covering what you need to know about the legacy system for context and migration awareness.

Beyond the paywall UI itself, you'll also need to decide on a monetization strategy. This tutorial covers two primary approaches:

• Hard Paywall — gates all app features behind a single entitlement
• Freemium — provides free core access and prompts users to upgrade to paid tiers

We'll walk through both strategies so you can choose the right one for your app.

Installing the RevenueCat SDK and RevenueCatUI Package

Before you can display any paywall, you need to install the RevenueCat SDK and its UI package.

Step 1: Install the Core RevenueCat SDK

The RevenueCatUI package (which contains Paywalls) is an extension of the core RevenueCat SDK. You must install the core SDK first before adding paywall functionality. Refer to the RevenueCat installation guides for your target platform.

Unity Developers: For Unity projects, install the core RevenueCat Unity SDK first by following the Unity installation guide, then install the purchases-unity-ui package for paywall support. Source

Step 2: Install the RevenueCatUI Package

RevenueCat Paywalls are included as part of the RevenueCatUI package in the RevenueCat SDK. You'll need to install the RevenueCatUI package in your project to use Paywalls.

Step 3: Verify SDK Version Compatibility

Not all SDK versions support the new Paywall Builder. Ensure your project meets the minimum recommended versions for the new paywall system Source:

Important: The legacy paywall system has different minimum version requirements. See the Legacy vs. New Paywall Builder section below for a comparison.

Supported Platforms (New Paywall Builder)

The new Paywall Builder supports the following platforms:

• ✅ iOS 15.0 and higher
• ✅ Android 7.0 (API level 24) and higher
• ✅ Mac Catalyst 15.0 and higher
• ✅ macOS 12.0 and higher
• ✅ Web (modern browsers)
• ✅ visionOS
• ❌ watchOS (not yet supported)
• ❌ tvOS (not yet supported)

Web Installation

For web projects, install @revenuecat/purchases-js and follow the Web SDK installation guide. Once configured, you can present your remotely managed paywall using presentPaywall. Source

Choosing Your Paywall Monetization Strategy

With your SDK installed, the next critical decision is which monetization model your paywall will enforce. RevenueCat supports two primary strategies, each with its own implementation path.

Strategy 1: Hard Paywall

"A hard paywall strategy is straightforward: users must purchase to access specific content or features." Source

The Hard Paywall model gates all features of your app behind a single entitlement. There is no free tier — users must subscribe or purchase before they can use the app.

This model works well when:

• Your app provides high-value content or functionality
• Your app operates with high unit economics (e.g., AI-driven features with significant per-user costs)
• You have a clear value proposition
• Your target audience has a high willingness to pay

Implementation focus: Configuration and paywall display to maximize direct conversion.

Strategy 2: Freemium

"This guide walks through implementing and optimizing a Freemium strategy using RevenueCat, focusing on how to manage entitlements, display upgrade prompts, and convert free users into paying customers with minimal friction." Source

The Freemium model provides free access to core features while prompting users to upgrade to paid tiers for advanced functionality.

This model works well when:

• There is a clear and compelling upgrade path from free to paid (e.g., feature gating, usage limits)
• The app has low marginal costs per user (minimal server or infrastructure overhead)
• Your strategy is to leverage freemium users as growth drivers through sharing, referrals, or collaboration
• The app faces competitive pressure where users expect to try the core experience before subscribing

Implementation focus: Managing entitlements to distinguish free vs. paid access, displaying contextual upgrade prompts, and converting free users into paying customers.

Which Strategy Should You Choose?

Setting Up Entitlements for Your Paywall

Regardless of which monetization strategy you choose, entitlements are the foundation of your RevenueCat paywall implementation.

"RevenueCat Entitlements represent a level of access, features, or content that a user is 'entitled' to. Entitlements are scoped to a project, and are typically unlocked after a user purchases a product." Source

Entitlements allow you to manage user access based on purchases without hardcoding product identifiers throughout your app code. Source

Entitlements for a Hard Paywall

For a Hard Paywall, the entitlement setup is intentionally simple.

Taking into consideration the fact that hard paywalls block the main feature access of your app, RevenueCat recommends creating a single-tier access level or entitlement that grants access to all features of the application.

Recommended approach:

1. Create a single entitlement (e.g., pro or full_access) in your RevenueCat project dashboard.
2. Attach all products (monthly, annual, lifetime, etc.) to this entitlement.
3. In your app code, check for this entitlement to determine whether the user can access the app.

// Example: Checking entitlement access (iOS/Swift)
let customerInfo = try await Purchases.shared.customerInfo()

if customerInfo.entitlements["full_access"]?.isActive == true {
    // User has purchased — grant access
    showMainApp()
} else {
    // No active entitlement — show paywall
    showPaywall()
}

Entitlements for a Freemium Model

For Freemium, you need to carefully define both your free and premium feature sets before configuring entitlements:

Before you configure entitlements, define:

• Free features: Core functionality, basic features that showcase value, features that encourage engagement
• Premium features: Advanced functionality, enhanced user experience, exclusive content or capabilities

Source

Recommended approach:

1. Create one or more entitlements representing your paid tiers (e.g., premium, pro, enterprise).
2. Leave free features accessible without any entitlement check.
3. Gate premium features behind entitlement checks, prompting an upgrade when the user hits a gated feature.

// Example: Freemium entitlement check (iOS/Swift)
let customerInfo = try await Purchases.shared.customerInfo()

if customerInfo.entitlements["premium"]?.isActive == true {
    // Show premium feature
    showAdvancedAnalytics()
} else {
    // Show upgrade prompt
    showUpgradePaywall()
}

For detailed entitlement configuration steps in the RevenueCat dashboard, refer to the RevenueCat entitlements documentation.

Displaying Products on Your Paywall

Once entitlements are configured, you need to display the right products on your paywall. RevenueCat's Offerings system is the mechanism for this — it allows you to group products and control which ones appear on your paywall remotely, without requiring app store resubmissions.

Making Your Paywall Dynamic

Dynamic paywalls allow product offerings to update without requiring app store re-submissions. This is a significant operational advantage — you can change pricing, trial lengths, or product groupings from the RevenueCat dashboard instantly.

You can use RevenueCat's Paywalls or Offering Metadata to remotely control and A/B test any aspect of your paywall. This means your paywall display logic can be entirely driven by server-side configuration.

A/B Testing Paywalls with Experiments

If you want to optimize your paywall's conversion rate, RevenueCat's Experiments feature lets you A/B test multiple paywall configurations (2–4 variants) and analyze the full subscription lifecycle to understand which variant produces more value for your business. Source

Experiments are based on RevenueCat Offerings, which means you can A/B test more than just prices, including: trial length, subscription length, different groupings of products, etc.

⚠️ Note: Experiments is available to Pro & Enterprise customers. Check RevenueCat's pricing page for plan details.

As long as your app fetches the current Offering from the RevenueCat SDK, Experiments will automatically serve the correct Offering for each user's assigned test variant — no additional app code required. Source

Legacy Paywalls vs. New Paywall Builder

Understanding the difference between these two systems is important — especially if you're working with an existing RevenueCat integration.

Key Differences

Source: New Paywalls | Source: Legacy Paywalls

Legacy SDK Version Requirements

If you are maintaining an app that uses the legacy paywall system, these are the SDK versions required Source: