Google Play Billing Library 5.0, an overview

At Google I/O 2022, the Google Play Team presented Google Play Billing Library 5.0 – the newest version of its in-app billing and subscriptions library.

In this blog post, we’ll go through:

• The biggest changes from PBL4 to 5.0;
• The timeline for deprecation of the older libraries and migration;
• An abbreviated Google Play Billing Library 5 migration guide;
• An update on RevenueCat’s support of the new billing library, and;
• A list of compiled resources to help answer questions and support your migration

Google Play’s new subscription model

With Google Play Billing Library 5, Google has fundamentally – and drastically – changed the structure used to define subscription products. This leads to significant changes to subscription management in the backend, as well as your app’s subscription implementation.

This new structure does away with the previous need to create unique SKUs for every subscription term, offer, etc and replaces it with a more flexible and organized approach. This should enable developers to more easily create and manage offers across the subscription lifecycle, ultimately leading to better end-user experience and higher monetization rates.

Play Billing Library 5 subscription architecture

From this version of the Billing Library onwards, single subscriptions can now have multiple base plans, and base plans can have multiple offers. In this new architecture:

• Subscriptions refer to a set of benefits that users can access during a period of time (what you sell). For example, a “Gold tier”
• Base plans refer to a specific configuration of billing period, renewal type and price (how you sell). For example, “annual with auto-renew”, “prepaid monthly”
• Offers refer to discounts available to eligible users of your app (any modifications to the base price). For example, “20% for monthly to annual upgrade”, “free 14-day trial for new users”

Previously, every unique combination of benefits, billing period and discount or offer, required its own subscription.

New functionality when using Google Play Billing Library 5.0

Through its system of subscriptions, base plans, and offers, PBL5 enables a number of new subscription features and configurations.

Among others, you can now:

• Offer prepaid plans. Instead of automatically renewing, these subscriptions need to be proactively extended by the user
• Easily manage price changes. Decide exactly when and for who pricing changes take place using pricing cohorts
• Control availability and pricing individually for regions and countries. This includes ‘new countries / regions’ which you use to set availability and pricing for any newly supported countries or regions
• Deactivate base plans and offers. Disable pricing configurations and discounts for new users, without changing or disabling the associated subscription
• Use tags to organize and manage. Tags allow you to define related groups of offers, base plans, and subscriptions to manage them in bulk
• Have more flexibility when defining offers. Utilize pricing phases to offer time-based discounts that’ll automatically convert to base pricing
• Granularly control eligibility. Through Offers, the business logic to determine eligibility can be moved entirely to your app, allowing highly targeted offers based on in-app behaviors

Play Billing Library 5.0 backwards compatibility

The changes made in Google Play Billing Library 5 necessitated some immediate changes to how subscriptions are created, displayed and managed in Play Console. To understand the impact of these changes, let’s take a look at the before-Google-I/O subscription setup in Play Console:

And what subscriptions look like in Play Console since mid-2022:

Here we see how Google has automatically migrated existing subscriptions to the new setup. Product ID moves over to a new subscription, with a base plan that matches the original billing period. If a subscription included a free trial or intro price, this converted to an offer automatically. In all cases, you’ll maintain the functionality of your original subscription.

Because Google Play Billing Library 4 and earlier expect a single billing period, price and (optionally) intro price per subscription, your converted legacy subscription contains a single ‘backwards compatible’ base plan and offer. You can now add additional base plans and offers to these converted subscriptions, but only the backwards compatible option will be available to apps that haven’t switched to the newer API methods.

Google Play Billing Library 3 and 4 deprecation timeline

As a rule, Google supports every version of their Play Billing Library for (at least) 2 years after it releases. This means that:

• Play Billing Library 3 can no longer be used in newly launched apps from August of 2022
• Play Billing Library 3 can no longer be used in updates to existing apps from November of 2022
• Play Billing Library 4 can no longer be used in newly launched apps from August of 2023
• Play Billing Library 4 can no longer be used in updates to existing apps from November of 2023
  

There’s still ample time to switch over, but Google has recommended that developers try and remain on the newest version of Play Billing Library at all times. That not every developer takes that advice to heart is clear when reviewing the PBL adoption by version in the Google Play SDK index:

Highlights of a Google Play Billing Library 4 to 5 migration

If you’re not using RevenueCat for Android in-app subscriptions, migrating from PBL4 to 5 involves multiple steps. We’ll share the highlights and most important changes you’ll need to make here, but you’ll find more details in Google’s integration guide, and billing specific samples on GitHub.

Creating a product catalog

Google recommends creating new products using the updated entity structure of Google Play Billing Library 5 before migrating your app. You can do this by consolidating the duplicate products that represent the same subscription benefits with different configurations of price, duration, etc.
This is the recommended first step as editing converted subscription products can result in issues with older versions of your app that still use PBL4 and deprecated methods like querySkuDetailsAsync().

Managing your catalog with the new API

If you manage your subscriptions automatically with the Developer API, there are three new endpoints to be aware of:

• Monetization.subscriptions to manage subscription products
• Monetization.subscrtipions.basePlans to manage base plans for your subscriptions
• Monetization.subscrtipions.basePlans.offers to manage the offers associated with your base plans

For anything but one-time purchases, these new endpoints should be used via the Subscription Publishing API. Your one-time purchases will still be managed via the inappproducts API previously used for subscriptions as well.

Updating the Billing Library dependency

Created your new products? You can now migrate your app by updating your Play Billing Library dependency in your build.gradle file:

dependencies {
	def billingVersion = "5.1.0"

	implementation "com.android.billingclient:billing:$billingVersion"
}

Note that on October 31st of 2022, Google released the Google Play Billing Library 5.1, which – if you’re implementing PBL5 now – should be the version you’re using.

Showing available products

Because we’ve switched from SKUs to Products, the calls required to show eligible offers have changed:

• Replace BillingClient.querySkuDetailsAsync() with BillingClient.queryProductDetailsAsync()
• Replace SkuDetailsParams with QueryProductDetailsParams

Query results have gone from SkuDetails to ProductDetails, showing you information about the product (title, type, ID, etc), similar to before. New is List<ProductDetails.SubscriptionOfferDetails>, which contains the available offers for a specific user. Note that – unlike in PBL4 – you’ll be able to see several different offers for the same subscription period. In some cases, Google will handle eligibility, but in other cases, you’re able to define which offers show up in the paywall.

Important: If you’re showing a personalized offer as determined by Art. 6 (1) (ea) CRD of the Consumer Rights Directive (2011/83/EU) to a user in the EU, you’re required to disclose this via the Play UI. To do this, customize setIsOfferPersonalized() with true or false, depending on the offers shown to your user.

Launching the purchase flow

There are very few changes here, beyond going from SKUs to offers:

• Use ProductDetailsParams instead of SkuDetails for BillingFlowParams
• Use SubscriptionOfferDetails to get offer ID, base plan ID and other offer details

You’ll then pass the offerToken for a selected offer into the ProductDetailsParams object to purchase a product.

Processing purchases

This also largely remains the same, but you will need to pass a QueryPurchasesParams object with a BillingClient.ProductType value, instead of a BillingClient.SkuType value to queryPurchasesAsync().

Managing subscription status via the API

Your current subscription purchase status management backend component will be able to manage converted subscriptions pre-dating May 2022 as well as backward compatible offers, but will not support any of the new functionality introduced in Google Play Billing Library 5. To fully support the new subscription features, implement the new Subscription Purchases API (link), which will check purchase status and manage entitlements in your backend.

Replace calls to purchases.subscriptions.get with purchases.subscriptionsv2.get to access a new resource called SubscriptionPurchaseV2. There, you’ll find the necessary information to manage entitlements for subscriptions created in the new model.

Testing Android subscriptions for Google Play Billing Library 5

Before launching your app or submitting your app’s update, – as always – thoroughly test your subscriptions. The process to do so doesn’t differ from how you did it in PBL4, so simply follow the steps detailed in our ultimate guide to Android subscription testing.

Migrating to Billing Library 5, from Android Dev Summit ‘22

At this year’s Android Dev Summit, Diana García Ríos from Google’s Android team presented on the topic of PBL5 migrations. In this 16 minute video, she explains how to adopt Android and server integrations to take advantage of these new capabilities, and cust maintenance load by designing your subscription system for PBL5 from the bottom up:

RevenueCat Google Play Billing Library 5 support, or “How to save yourself most of the hassle”

Our team aims to support Google Play Billing Library 5 as fast as possible, and expects to launch in Q1 of 2023. In the interest of the hundreds of millions of dollars in Google Play subscription revenue supported for 10,000+ Android apps on RevenueCat today – we’re making sure that our purchases-android SDK and backend are thoroughly vetted to work correctly with this new version of the Billing Library.

Until this update takes place, you’re still able to create new subscriptions and update price, trial durations, etc. The only caveat is that these subscriptions need to include backward-compatible base plans and offers, and RC will disregard any additional offers or base plans associated with a subscription product.

As we work towards supporting Google Play Billing Library 5, we’re recruiting for Beta testers. If you have interest and capacity to test with us please reach out to team-catforms@revenuecat.com. See our community post for more details on requirements. We’ll get back to you and explore if its a fit!

Useful resources

• Google Play Billing Library 5.0.0 and 5.1.0 release notes (link)
• Google Play’s May 2022 subscription changes (link)
• Google guide to integrating Google Play Billing Library into your app (link)
• Recent changes to subscriptions in Play Console (link)
• Understanding Google Play subscriptions, May 2022 update (link)
• Codelab: Sell subscriptions in app with the Play Billing Library 5 (link)
• The ultimate guide to Android subscription testing