Paywall issues typically involve display problems, missing products, or non-functional purchase buttons. This section covers common paywall configuration challenges.

Issue 1: Paywall Not Displaying

Symptoms

• Paywall view doesn't appear.
• Blank screen where paywall should be.
• Crash when trying to show paywall.

Common Causes

1. No Published Paywall: Paywall exists in draft but not published.
2. RevenueCatUI Dependency Missing: Haven't imported the UI library.
3. Paywall Not Linked to Offering: No paywall associated with offering.
4. Wrong Offering Requested: Code requests offering that has no paywall.

Solution Steps

Step 1: Verify Paywall is Published

1. Go to RevenueCat dashboard.
2. Navigate to Paywalls.
3. Check your paywall status:
   • Draft: Not live yet.
   • Published: Live and available.
4. If still in draft, click Publish.

Step 2: Verify RevenueCatUI Dependency

iOS (SPM):

// In your code, verify you can import:
import RevenueCat
import RevenueCatUI  // ← Must have this for paywalls

iOS (CocoaPods):

pod 'RevenueCat'
pod 'RevenueCatUI'  # ← Add this line

Android (Gradle):

// Use purchases-ui instead of just purchases
implementation("com.revenuecat.purchases:purchases-ui:9.20.2")

Step 3: Verify Paywall is Linked to Offering

1. In RevenueCat dashboard, go to Paywalls.
2. Click on your paywall.
3. Check the Offering field shows the correct offering identifier.
4. If not set, edit and select the offering.

Step 4: Check Code Implementation

iOS (SwiftUI):

import RevenueCatUI

struct ContentView: View {
    @State private var showPaywall = false

    var body: some View {
        Button("Show Paywall") {
            showPaywall = true
        }
        .presentPaywallIfNeeded(
            requiredEntitlementIdentifier: "premium",
            isPresented: $showPaywall
        )
    }
}

Android (Compose):

import com.revenuecat.purchases.ui.revenuecatui.Paywall

@Composable
fun MyScreen() {
    var showPaywall by remember { mutableStateOf(false) }

    if (showPaywall) {
        Paywall(
            onDismiss = { showPaywall = false }
        )
    }
}

Issue 2: Products Not Showing on Paywall

Symptoms

• Paywall displays but product cards are empty.
• Prices show as $0.00 or blank.
• Product titles/descriptions missing.

Common Causes

1. Package Identifiers Mismatch: Paywall expects different package identifiers.
2. Products Not Available: Store products can't be fetched.
3. Missing Localization: Product info not configured for user's locale.
4. Offering Empty: No products in the offering.

Solution Steps

Step 1: Verify Package Identifiers Match

1. In paywall editor, check which package identifiers are used.
2. Common package identifiers:
   • $rc_monthly.
   • $rc_annual.
   • $rc_lifetime.
3. In Product Catalog → Offerings, verify your packages use these identifiers.
4. If using custom identifiers, update paywall to match.

Step 2: Test Product Fetching

// Test if products are being fetched
let offerings = try await Purchases.shared.offerings()

if let offering = offerings.current {
    for package in offering.availablePackages {
        print("Package: \(package.identifier)")
        print("  Product: \(package.storeProduct.localizedTitle)")
        print("  Price: \(package.storeProduct.localizedPriceString)")
    }
} else {
    print("No current offering")
}

If this prints products correctly but paywall doesn't show them, it's a paywall configuration issue.

Step 3: Check Product Localization

For iOS (App Store Connect):

1. Go to your product in App Store Connect.
2. Check Localization section.
3. Add localization for user's language/region.
4. Provide display name and description.

For Android (Google Play Console):

1. Go to your product in Google Play Console.
2. Check Translations.
3. Add translations for target languages.

Issue 3: Purchase Button Not Working

Symptoms

• Tapping purchase button does nothing.
• Button tap shows loading but never completes.
• Error appears when trying to purchase.

Common Causes

1. Purchase Delegate Not Set: No handler for purchase completion.
2. Entitlement Check Failing: User already has entitlement but UI doesn't reflect it.
3. Transaction Not Finishing: SDK configured to not auto-finish transactions.
4. Network Issues: Can't communicate with store servers.

Solution Steps

Step 1: Implement Purchase Callback

iOS:

.presentPaywallIfNeeded(
    requiredEntitlementIdentifier: "premium",
    purchaseCompleted: { customerInfo in
        // Handle successful purchase
        print("Purchase completed! Access granted.")
    },
    restoreCompleted: { customerInfo in
        // Handle restore
        print("Restore completed!")
    }
)

Android:

Paywall(
    onPurchaseCompleted = { customerInfo ->
        // Handle successful purchase
        Log.d("Paywall", "Purchase completed!")
    },
    onRestoreCompleted = { customerInfo ->
        // Handle restore
        Log.d("Paywall", "Restore completed!")
    },
    onDismiss = { showPaywall = false }
)

Step 2: Verify Auto-Finish is Enabled

Check your SDK configuration ensures transactions finish automatically:

// iOS - this is the default, no configuration needed
Purchases.configure(withAPIKey: "appl_xxx")

// Android - verify this is set
val builder = PurchasesConfiguration.Builder(this, "goog_xxx")
Purchases.configure(
    builder
        .purchasesAreCompletedBy(PurchasesAreCompletedBy.REVENUECAT)  // ← Important!
        .build()
)

Step 3: Enable Debug Logging

See what's happening when purchase button is tapped:

// iOS
Purchases.logLevel = .debug

// Android
Purchases.logLevel = LogLevel.DEBUG

Common Issues Quick Reference

Quick Paywall Troubleshooting Checklist

• RevenueCatUI dependency added.
• Paywall published (not draft).
• Paywall linked to offering.
• Package identifiers match between paywall and offering.
• Products are fetchable (test with offerings API).
• Product localization configured for user's locale.
• Purchase completion callbacks implemented.
• Auto-finish transactions enabled.
• Debug logging enabled.
• Testing with valid store configuration.