Preface

Building in-app purchases on Android from scratch means writing your own BillingClient connection management, product queries, purchase flow orchestration, server-side receipt verification, RTDN processing, subscription state machines, grace period logic, account hold handling, and error retry strategies. Getting all of that right is genuinely complex work, and the surface area is large.

This handbook shows you the same problems solved with RevenueCat.

The structure mirrors the original chapter for chapter. Where RevenueCat dramatically simplifies the implementation, you will see the code. Where RevenueCat makes an entire problem disappear, where the answer to "how do I implement this?" is "you don't have to", you will find a short explanation of what RevenueCat handles on your behalf and what, if anything, you still need to do.

The goal is not to sell you on RevenueCat. It is to give you an honest map of the tradeoffs. RevenueCat does not make in-app purchases trivial. It moves complexity from your code into a managed service. That tradeoff is worth understanding clearly before you commit to either approach.

What RevenueCat Is

RevenueCat is a backend service and client SDK for managing in-app purchases and subscriptions. On Android, the SDK wraps BillingClient internally. You never call BillingClient directly. Instead you call Purchases, the RevenueCat SDK singleton, and it handles the Google Play Billing protocol on your behalf.

The SDK does three things:

1. Client-side purchase orchestration. Purchases wraps BillingClient, manages the connection lifecycle, launches purchase flows, handles acknowledgement and consumption, and retries transient errors automatically.
2. Backend receipt verification. After every purchase, the SDK posts the purchase token to the RevenueCat backend. RevenueCat calls the Google Play Developer API to verify the receipt, records the transaction, and returns a CustomerInfo object describing the user's current entitlements.
3. Entitlement management. RevenueCat maintains a server-side record of every user's active entitlements. Your app checks customerInfo.entitlements["pro_access"]?.isActive to decide whether to grant access. You never query the Google Play Developer API directly.

What This Handbook Assumes

This handbook assumes you have read the companion handbook or have equivalent experience with Google Play Billing. Concepts like base plans, offers, replacement modes, RTDNs, purchase tokens, and subscription states are used here without full re-explanation. The focus is on how RevenueCat maps to those concepts, not on explaining the concepts themselves.

You should be comfortable with Kotlin coroutines. The code examples use the RevenueCat coroutine extension functions (awaitOfferings(), awaitPurchase(), etc.) throughout.

SDK Version

All code examples in this handbook target RevenueCat Android SDK 9.x, which wraps Google Play Billing Library 8.x internally. SDK 9.x requires Kotlin 1.8.0 or higher and no longer supports querying expired subscriptions or consumed one-time products, a limitation imposed by Play Billing Library 8.