An overview of Google Play Billing Library 5

Still working on your Play Billing Library 5 migration? All our SDKs have supported PBL 5 for multiple versions, and our main Android SDK is on Billing Library 6. Why not move to RevenueCat today and save yourself the same deprecation stress next year? Click here for our Android docs, or talk to us if you need help migrating.

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

In this blog post, we’ll go through:

• The biggest changes from version 4 to 5;
• 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 billing period, 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

Through its system of subscriptions, base plans, and offers, Google Play Billing Library 5 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. This may be of most interest for apps serving markets with limitations on auto-renewing subscriptions, like India. 
• Easily manage price changes. Decide if users should enter into the legacy price cohort and if/when their price should increase
• 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 developer determined offers, the business logic to determine eligibility can be moved entirely to your app, allowing highly targeted offers based on in-app behaviors
• Sell the same products with different offers, some of which can be determined by Google Play (like previous free trials), and others by the developer

Play Billing Library 5 backwards compatibility

The changes made in Google Play Billing Library 5 required 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 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 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

The timeline to switch over is fast approaching andGoogle 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 Google Play Billing Library 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 Billing Library 4 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 Billing Library 4 and deprecated methods like querySkuDetailsAsync().

Managing your catalog with the new API

If you manage your subscriptions automatically with the Google Play 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 Play Billing Library 5 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 all the base plans and available offers for a specific user. Note that – unlike in Billing Library 4 – 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.

Due to the new subscription model structure, accessing one time purchases details also received a change. The pricing details are now in a ProductDetails.OneTimePurchaseOfferDetails object rather than on ProductDetails.

Launching the purchase flow

Instead of providing just the product and using the default offer in the purchase, the developer can now select the specific offer to be applied to the user: 

• 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 subscription  or you’ll pass the ProductDetails into the ProductDetailsParams object to purchase a one time 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().

Changing Subscriptions

It’s common that users will want to change their subscription at some point. They may want to change their duration (ex: from monthly to annually) or to a completely different subscription tier (ex: silver to gold). Google offers five different proration modes that developers can choose from when changing subscriptions. These proration modes affect how much and when the user gets billed and also when the new subscription starts. These modes are:

• IMMEDIATE_WITH_TIME_PRORATION
• IMMEDIATE_WITHOUT_PRORATION
• IMMEDIATE_AND_CHARGE_PRORATED_PRICE
• IMMEDIATE_AND_CHARGE_FULL_PRICE
• DEFERRED

One undocumented change is that IMMEDIATE_WITH_TIME_PRORATION won’t work for every use case. It will error when trying to change between base plans within the same subscription but will work when changing to a completely different subscription. This seems like something Google might be fixing in a future release but as of right now it doesn’t work for base plans.

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. One limitation that is worth noting is that the new resource no longer contains pricing information, so if you rely on data from this API to analyze revenue or lifetime value, you will have to capture price data through another channel.

The purchases.subscriptionsv2 REST API resource does not contain any methods to acknowledge, cancel, refund, revoke or defer a subscription, so you will still need to use the previous purchases.subscriptions resource for that.

Real Time Notifications

The Pub/Sub payload for  real time purchase notifications has changed. The body will no longer include subscriptionId. This subscriptionId was previously needed to make an API call using purchases.subscriptions.get to check subscription status.  Now, you’ll have to use the new purchases.subscriptionsv2.get with a purchase token to get subscription statuses.

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 Billing Library 4, 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 Google Play Billing Library 5 migrations. In this 16 minute video, she explains how to adopt Android and server integrations to take advantage of these new capabilities, and custom maintenance load by designing your subscription system for Billing Library 5 from the bottom up:

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

As we’ve covered, Google Play Billing Library 5 has meaningfully changed the structure used to define subscription products. Unlike previous Billing Library iterations, version 5 has completely new backend APIs with different data structures, meaning that the backend code requires a near-complete rewrite. Luckily, RevenueCat can save your team the scramble, hassle and errors that come with migrating on your own.

RevenueCat’s in-app purchase and subscription Infrastructure provides a backend and wrapper around Google Play Billing, Apple StoreKit and other platforms to simplify the implementation of in-app purchases, reduce your maintenance backlog, and provide clean and consistent data.

Our Android SDK and backend now support Google Play Billing Library 5. Whether you are an existing RevenueCat customer or looking to become one, our purchases-Android SDK is the easiest way to use the new features of Google Play Billing Library 5. There is no need to worry about implementing any of the Billing Library SDK changes, new REST APIs or adopting the new subscription model structure. RevenueCat has taken care of all the heavy lifting. 

Some of the ways RevenueCat saves you the hassle

Managing subscription status via the API

The most pressing challenge with the new purchase endpoints is figuring out how much was charged for a subscription. Unlike Billing Library 4, prices are not returned via the API with Billing Library 5. This means, if you were to migrate to Billing Library 5 yourself, you would have to implement a call to get the subscription pricing at time of each purchase and store on your own backend.  If you’re a RevenueCat user, you won’t have to worry about this as we capture prices SDK-side and server-side so that we can have accurate revenue figures in Charts, your integrated marketing stack, data exports and more- saving you significant backend work.

As the new endpoint doesn’t provide any pricing information, this poses an issue if you plan to update your prices regularly.  Without RevenueCat, you’d have to be willing to avoid changing your prices frequently or to hard code the prices in the backend for all the regions in order to get an accurate picture of money made.

RevenueCat addresses this challenge because we have built mechanisms to pull in pricing information from the SDK and/or recreate the pricing information by comparing information about the plan with the current status of the purchase.

Managing your product catalog with the new API

Because Billing Library 4 and earlier expect a single billing period, price and optional introductory price per subscription, your converted legacy subscription contains a single ‘backwards compatible’ base plan and offer. In version 5, 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. RevenueCat allows for older versions of the app to still function while allowing developers to set products with the full set of functionality for Billing Library 5 apps.  Based on which version of the app hits our backend, we will choose whether to use your backwards-compatible products or the Billing Library 5 app’s products which take advantage of new features.

Showing Available Products

As a result of the complex new product configurations, Billing Library 5 can make it more challenging to display the offerings you want on your paywall. Because Google has switched from SKUs to Products, the calls required to show eligible offers have changed. RevenueCat’s SDK interface makes dealing with these complications easier. With Billing Library 4, if you offered a subscription with a free trial, Google would automatically apply the free trial. Since you can add unlimited offers with Billing Library 5, Google no longer applies this automatically, and you have to explicitly pick and choose the trial through code. RevenueCat has built-in logic to determine what the “best offer” is and will automatically apply that if the developer chooses. This is especially helpful in cases where there is only one offer eligible to be applied. 

---

With the deadlines for switching to Play Billing Library 5 fast approaching (August 2023 for new apps and November 2023 for updates to existing apps) we’d encourage you to start considering your migration plan today. 

Useful resources

Get Started with RevenueCat 

Migrating your subscriptions for your Android app over to RevenueCat will save you the trouble of adopting Google Play Billing Library 5 and any future updates from Google and the other platforms. To get started with RevenueCat, explore our migration guide docs. If you have more complex needs, we encourage you to request a custom migration plan from our team.

Resources for Apps using RevenueCat 

If you want to make use of the new features available with Billing Library 5, review our docs for the simple steps you can take to adapt your existing code. Otherwise, no action is required and your existing products will continue functioning as expected.

Resources from Google 

• 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