--- title: "Introducing Google Play Billing & RevenueCat Handbooks" description: "In this article, you'll explore what each handbook covers, how the two line up chapter by chapter, and which reading path fits your situation." language: "en" publishedAt: "2026-10-22T04:29:14.232Z" updatedAt: "2026-10-22T04:29:14.232Z" authors: - name: "Jaewoong Eum" url: "https://www.revenuecat.com/blog/author/jaewoong-eum" category: "Engineering" categoryUrl: "https://www.revenuecat.com/blog/engineering" canonical: "https://www.revenuecat.com/blog/engineering/google-play-handbook" --- # Introducing Google Play Billing & RevenueCat Handbooks In this article, you'll explore what each handbook covers, how the two line up chapter by chapter, and which reading path fits your situation. ## Table of contents - [The Google Play Billing Handbook: Building it yourself](#the-google-play-billing-handbook-building-it-yourself) - [The RevenueCat Android SDK Handbook: The same problems, solved with the SDK](#the-revenuecat-android-sdk-handbook-the-same-problems-solved-with-the-sdk) - [Reading the handbooks side by side](#reading-the-handbooks-side-by-side) - [Choosing a reading path](#choosing-a-reading-path) - [The handbooks as agent skills](#the-handbooks-as-agent-skills) - [Installing the skills](#installing-the-skills) - [Beyond the handbooks: Play Billing Library 9 and SDK 10](#beyond-the-handbooks-play-billing-library-9-and-sdk-10) - [Conclusion](#conclusion) Getting a first purchase working with the Play Billing Library (PBL) can take more than just several days. Getting subscriptions right in production takes much longer: a subscription moves through a state machine, a failed renewal passes through a grace period and an account hold, your backend has to verify every purchase token, and lifecycle events arrive as Real Time Developer Notifications (RTDN) through Cloud Pub/Sub. Google's documentation covers every piece of this, spread across dozens of pages that you have to connect yourself. RevenueCat has published two free handbooks that each put the whole lifecycle in one place: one for building directly on the Play Billing Library, and one for building on the RevenueCat Android SDK. In this article, you'll explore what each handbook covers, how the two line up chapter by chapter, which reading path fits your situation, how the companion skills bring the same material into your coding agent, and what has shipped since the handbooks were written. ## **The Google Play Billing Handbook: Building it yourself** [The Google Play Billing Handbook](https://www.revenuecat.com/guides/google-play-billing) is written for Android developers who know Kotlin, Activities, ViewModels, and Gradle but know Google Play Billing only partly or not at all. It takes you from zero billing knowledge to a production ready integration. The 18 chapters are organized in seven parts that build on each other: 1. **Foundations** (chapters 1 and 2): how Google Play's billing system fits together, and how to set up your environment. 1. **Products** (chapters 3 and 4): one time products and subscriptions. 1. **Client side integration** (chapters 5 to 8): the Play Billing Library, the purchase flow, plan changes, and error handling. 1. **Server side integration** (chapters 9 and 10): purchase verification with the Google Play Developer API, and RTDN. 1. **The subscription lifecycle** (chapters 11 to 14): the subscription state machine, payment recovery, cancellations, pauses, winback, and price changes. 1. **Production readiness** (chapters 15 to 17): security and fraud prevention, testing, and catalog management at scale. 1. **Beyond standard billing** (chapter 18): alternative billing and external offers. Five appendices, A to E, collect the material you look up rather than read: a complete RTDN reference table, a `BillingResult` response code reference, a Google Play Developer API quick reference, a migration guide from PBL 7 to PBL 8, and a pull out subscription state diagram. The code is Kotlin on both the client and the server, so you read the whole integration in one language, and the client code uses the coroutine extensions from the `billing-ktx` artifact. The handbook targets Play Billing Library 8, specifically versions 8.0.0 through 8.3.0, and the last section of this article covers what has shipped since. You can read every chapter on the web or download the whole handbook as a [287 page PDF](https://www.revenuecat.com/documents/google-play-handbook), and neither requires signing up. ![](https://cdn.sanity.io/images/c3qnx9b0/production/2ffae0677b136f7049c342bb70b106764ec75f88-1624x1038.png) ## **The RevenueCat Android SDK Handbook: The same problems, solved with the SDK** [The RevenueCat Android SDK Handbook](https://www.revenuecat.com/guides/revenuecat-android-sdk/understanding-revenuecat) is for developers who have read the first handbook or have equivalent experience with Google Play Billing, and it solves the same problems with the SDK. Because it assumes that background, it uses concepts like base plans, offers, replacement modes, and purchase tokens without explaining them in full again. Its structure mirrors the first handbook chapter for chapter. Where the SDK simplifies an implementation, the chapter shows the code. Where the SDK removes a problem entirely, the chapter explains what RevenueCat handles on your behalf and what, if anything, you still need to do. Two appendices close the handbook. Appendix A is a quick reference for the SDK's API. Appendix B compares what RevenueCat replaces on the client and on the server, and lists what remains your responsibility. The code uses the SDK's coroutine extensions, such as `awaitOfferings()` and `awaitPurchase()`, and targets RevenueCat Android SDK 9.x, which wraps Play Billing Library 8.x. The handbook is available on the web and as a free [63 page PDF](https://www.revenuecat.com/documents/revenuecat-handbook), whose cover calls it The RevenueCat Handbook. ![](https://cdn.sanity.io/images/c3qnx9b0/production/9f345b84d027665a6ce806adfc72eb8ad5305502-1237x1160.png) ## **Reading the handbooks side by side** Because the chapter numbers match, you can open the same chapter in both handbooks and see how the work changes. A few pairs show the pattern: ![](https://cdn.sanity.io/images/c3qnx9b0/production/87fc962c51e2e1e8d18fac67560a978880519544-1600x1471.png) Not all of the gap between 287 and 63 pages, both at A4 size, is work that the SDK takes over. The first handbook has 38 pages of appendices against 7, explains concepts the second one assumes, and spends 19 pages on Google's alternative billing programs, which the second covers in one page because the SDK had no dedicated APIs for them when the handbook was written. Where the SDK does take over the work, the gap is real: the chapters on integrating the library, the backend, notifications, and subscription states run 60 pages in the first handbook and 11 in the second. ## **Choosing a reading path** The Google Play Billing Handbook's preface suggests two paths depending on where you start, and a third one fits if you're evaluating RevenueCat: - **Building a new integration from scratch**: read the first four parts (chapters 1 to 10) in order, then the subscription lifecycle chapters as you prepare for production, and the production readiness chapters before launch. - **Upgrading an existing integration from PBL 7**: start with Appendix D, the PBL 7 to PBL 8 migration guide, then read the chapters that cover your knowledge gaps. - **Deciding whether to use RevenueCat**: start with Appendix B of the RevenueCat handbook, then read the chapter pairs for the parts of the lifecycle that matter most to your app. ## **The handbooks as agent skills** A coding agent doesn't need a 287 page book to handle one failed renewal. It works better with short, task oriented instructions that it loads only when your request calls for them. [Play Billing Skills](https://github.com/RevenueCat/play-billing-skills) turns both handbooks into 45 agent skills, split into two collections that answer the same questions at two layers. The `google-play/` collection has 25 skills for the raw Play Billing Library, the Google Play Developer API, and RTDN, derived from the Google Play Billing Handbook. The `revenuecat/` collection has 20 skills for the RevenueCat Android SDK, RevenueCat's REST API, and webhooks, derived from the RevenueCat Android SDK Handbook. Most skills distill one chapter or appendix of their source handbook into a numbered workflow, and the YAML frontmatter at the top of every skill records where it came from. In the repository, the webhooks skill starts like this: ``` name: webhooks description: Use this skill when consuming RevenueCat webhooks on your backend. Covers the normalized event schema, the full event type list, idempotency via the event id field, and the correct handling for CANCELLATION versus EXPIRATION versus RENEWAL. license: Apache-2.0; see LICENSE metadata: author: RevenueCat source: revenuecat-handbook chapter 10 keywords: - android - revenuecat - webhooks - event-types - idempotency - cancellation - expiration ``` The `description` is what the agent matches your request against, and the `source` field ties the skill back to the chapter you can read yourself. ### **Installing the skills** The `revenuecat/` collection also ships as the `revenuecat-play-billing` plugin in the [RevenueCat AI Toolkit](https://github.com/RevenueCat/ai-toolkit) marketplace. In Claude Code, add the marketplace, then install the plugin next to the main `revenuecat` plugin, which connects the agent to your RevenueCat project through the MCP server: ``` claude plugin marketplace add RevenueCat/ai-toolkit claude plugin install revenuecat@RevenueCat claude plugin install revenuecat-play-billing@RevenueCat ``` The plugin is also available in Cursor, in Codex after `codex plugin marketplace add RevenueCat/ai-toolkit` and `codex plugin add revenuecat-play-billing@RevenueCat`, and in VS Code, where plugin marketplaces are still experimental. Gemini CLI installs one extension per GitHub repository and only picks up the main plugin, so on Gemini CLI, install the skills from the Play Billing Skills repository instead. The `google-play/` collection isn't in the plugin. To install both collections, clone the repository and run its install script: ``` git clone https://github.com/RevenueCat/play-billing-skills.git ~/play-billing-skills ~/play-billing-skills/scripts/install-skills.sh ``` he script links every skill into `~/.claude/skills` and prefixes each link with `gp-` or `rc-`, so both collections can be installed side by side even where they share a name, such as `setup` and `purchase-flow`. If you already installed the plugin, run the script with `--only google-play` so that the RevenueCat skills aren't installed twice. The repository's README covers the script's other options, such as installing into a single project, and how to point Android Studio's agent mode, Gemini CLI, and Cursor at the skill files. Once the skills are installed, you describe the task in plain language: "Handle RevenueCat webhooks on our backend. Ignore duplicate deliveries, and don't revoke access on a cancellation until the subscription actually expires." Claude Code picks skills by matching your request against each skill's description, so this request can load the webhooks skill shown above, installed as `rc-webhooks`. The skill has the agent deduplicate events by `event.id`, treat `CANCELLATION` as a subscriber turning off auto renew rather than as an access change, and revoke access on `EXPIRATION`. ## **Beyond the handbooks: Play Billing Library 9 and SDK 10** Both handbooks target Play Billing Library 8, which has been the minimum for new apps and app updates since August 31, 2026, with an extension available on request until November 1, 2026. Since the handbooks were written, Google has shipped PBL 9.0.0 (May 19, 2026) and 9.1.0 (June 18, 2026). For Play Billing Library 9.0, read [Google I/O 2026: What's New in Google Play and Play Billing Library 9.0](https://www.revenuecat.com/blog/engineering/play-billing-v9). It walks through the four code level changes in 9.0.0 and the billing changes aimed at involuntary churn, so it picks up where the Google Play Billing Handbook stops. Version 9.1.0 added the Billing Choice APIs, which [the complete guide to Google Play's Billing Choice](https://www.revenuecat.com/blog/engineering/play-billing-choice) covers. If you're still on v7, [the v7 to v8 migration guide](https://www.revenuecat.com/blog/engineering/play-billing-8-migration) pairs with Appendix D. The skills have already moved past the handbooks on library versions. The `google-play/` collection targets Play Billing Library 9 and adds two migration skills for it: one for apps on 8.x, and one that takes a 7.x integration to 9.x in two stages, through the v8 changes first. One lifecycle figure is out of date in both the Google Play Billing Handbook and the `google-play/` skills, which describe account hold as lasting up to 30 days. Since December 1, 2025, Google sets the account hold length automatically by default, to 60 days minus any grace period, and you can still choose a custom length in the Play Console. On the RevenueCat side, the Android SDK is on 10.x today and still wraps Play Billing Library 8.3.0, so the handbook's PBL 8 basis matches the SDK's billing layer. The handbook's main APIs are still in the SDK, with one deprecation: 10.3.0 introduced `StoreReplacementMode` and `replacementMode()`, which replace the `GoogleReplacementMode` enum and the `googleReplacementMode()` builder method that chapter 7 uses. ## **Conclusion** Keep the Google Play Billing Handbook close when you need to understand what Google Play is actually doing, such as why a subscription is on hold or what happens to the purchase token after a plan change. Its appendices work best as the reference material they were written to be. Reach for the RevenueCat handbook when you're evaluating RevenueCat or integrating it, and read Appendix B before you decide what to build yourself. If you work with a coding agent, install the skills so that its billing answers start from these handbooks instead of from whatever version of the library it happened to be trained on. Reading the same chapter in both handbooks is a direct way to see what an SDK takes on for you. The subscription lifecycle doesn't get any simpler when you change layers. What changes is which parts of it live in your code.