Migrating to Google Play Billing Library 5
Tags: android, subscriptions, mobile, googleplay
Published: 2022-11-25 16:06:47

At [Google I/O 2022](https://io.google/2022/program/e1fe8007-7338-4e33-814b-ecbfcb706c5e/), the Google Play Team presented Google Play Billing Library 5.0 – the newest version of its in-app billing and subscriptions library.

In this post, we'll go through some of the main steps you need to take to migrate your Android app from Google Play Billing Library 4 to PBL5.

_This is an excerpt of a post first published on the RevenueCat blog, where you'll find more information on [Google Play Billing Library 5](https://www.revenuecat.com/blog/engineering/google-play-billing-library-5-0/)_

_Also, the cover image is what DALL·E makes of the prompt "A cat hugging the Google Play logo"_ 😅

## Highlights of a Google Play Billing Library 4 to 5 migration
If you’re not using RevenueCat for [Android in-app subscriptions](https://www.revenuecat.com/blog/engineering/android-in-app-subscriptions-tutorial/), 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](https://developer.android.com/google/play/billing/integrate), and billing specific [samples on GitHub](https://github.com/android/play-billing-samples).

### 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](https://developer.android.com/google/play/billing/release-notes#5-1) 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.querySkyDetailsAsync()` 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)](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=celex%3A32011L0083) 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](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.subscriptionsv2)), 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 [RevenueCat's ultimate guide to Android subscription testing](https://www.revenuecat.com/blog/engineering/the-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:

{% embed https://www.youtube.com/watch?v=QcgAw1EJfrE %}

## Want to save yourself some pain?
RevenueCat was built to help developers manage the complexity of offering subscriptions across their mobile applications and web. Read more on our support for [Android in-app subscriptions here](https://www.revenuecat.com/blog/engineering/android-in-app-subscriptions-tutorial/), or [sign up](https://app.revenuecat.com/signup) and start building