Introducing Google Play Billing Library 7: New Features and Migration Guide

Considering your migration to Play Billing Library 7? RevenueCat’s Android SDK supports PBL7 right now! We‘ have‘ve been first out of the gate with support for major new Play Billing Library versions, ensuring you don’t have to worry about deprecation timelines. Why not move to RevenueCat today and save yourself the deprecation stress each year? Click here for our Android docs, or talk to us if you need help migrating.

At 2024’s Google I/O, sandwiched between the many (many) mentions of AI and Gemini, the Google Play Team presented Google Play Billing Library 7 – the latest and greatest version of their in-app billing and subscriptions library. As always, a new Play Billing Library (PBL) version means deprecation of an older version, so by the end of this year (November to be precise), you’ll need to have moved on from Play Billing Library 5, to either PBL 6 or 7. If you’re on Play Billing 6 today, you have another year until you’ll be forced to migrate off to a newer version.

In this blog post we’ll take you through:

• New functionality and important changes in Play Billing Library 7;
• The timeline for deprecation of Play Billing Libraries 5 and 6;
• A short migration guide if you’re looking to move to Play Billing 7;
• An update on expected support from RevenueCat for this new billing library, and;
• A list of resources to help answer any remaining questions and support your migration to PBL 7

Key changes in Google Play Billing Library 7

With Play Billing Library 5, Google totally upended how subscriptions functioned in Google Play. In contrast, Billing Library 6 offered only minor changes, mostly to how subscription statuses were handled from a technical perspective. With Google Play Billing Library 7, the Play team found a happy middle, combining tweaks to APIs and API endpoints with new customer facing functionality. We won’t list every change (that’s what release notes are for), but let’s dive into the biggest changes:

Virtual Installment Subscriptions in Billing Library 7

An obvious standout feature in this new release is the introduction of installment subscriptions. This new model allows users to pay for subscriptions in smaller, more manageable installments rather than a lump sum. This added flexibility reduces upfront financial commitments, potentially increasing subscription rates by making your service more accessible. That being said, Google explicitly states in the related documentation that as a developer you’ll still receive your payouts monthly for an annual plan with monthly installments. Even more notably, when a user fails to make an installment payment, neither Google or the developer will attempt to collect such payments, which makes the utility of this particular feature over – say – a regular monthly subscription quite limited.

Note that, for now, Play Billing Library 7’s installment subscriptions feature is only available in Brazil, France, Italy, and Spain. Google advises developers to keep an eye on Play Console for the latest availability. To enable installment subscriptions, implement ProductDetails.InstallmentPlanDetails based on this guide written on the topic by Google.

Pending Purchases for Subscriptions

Play Billing Library 7 supports pending transactions for pre-paid subscriptions (previously only available for non-recurring payments). These are transactions that require one or more additional steps between user initiation and the payment method being processed. For example, a user could start a transaction which involves them paying cash at a physical location. There were also several refinements to how transaction statuses for all pending purchases are handled, and new APIs to support the use case around pre-paid subscriptions.

Developers can call enablePendingPurchases() as part of initializing the Play Billing Client to enable pending transactions for their non-recurring payments, with PendingPurchasesParams.Builder.enablePrepaidPlans() added specifically to enable the functionality for pre-paid plans.

Purchase history via the API

If you’re using BillingClient.queryPurchaseHistoryAsync() to query purchase history today, you have about 1.5 years (until the deprecation of Play Billing Library 6) to move away from that particular API, because from Play Billing Library 7 onwards, it’s deprecated. From the documentation and I/O content it’s not entirely clear why, but for most use cases acceptable alternatives are suggested. Notable exception is consumed purchases. If you’re using .queryPurchaseHistoryAsync() to keep track of those today, you’re advised to keep track of that on your own servers going forward.

Play Billing Library 5 and 6 deprecation timeline

Now that Google Play Billing Library 7 is out and about, the clock has started ticking for deprecation of the 2 versions of Billing Library currently still supported: 5 and 6.

The support timeline for these versions is as follows:

• Google Play Billing Library 5 (including any minor versions) will be deprecated as of August 31, 2024. All new apps and updates to existing apps must use Billing Library version 6 or newer by August 31, 2024. If you need more time to update your app, you will be able to request an extension until Nov 1, 2024 from Google.
• Google Play Billing Library 6 (including any minor versions) can be used to release new apps until August 1st 2025, at the latest and can be used to release updates to existing apps until November 1st 2025

As evident when checking out Play Billing Library in the Google Play SDK Index, not everyone actually manages to hit these deadlines, which – as long as you don’t need to update your app – shouldn’t have any end-user facing consequences.

(Play Billing Library version adoption, as recorded on May 14th 2024)

Migration to Google’s Play Billing Library 7

If you’re not using RevenueCat for Google Play subscription handling, migrating to Billing Library 7 will require a bit of work. Below, we’ve shared the highlights and most important changes, but you can find additional information in this migration guide provided by Google.

Step 1: Update Dependencies

First, update your project’s dependencies to include Play Billing Library 7:

dependencies {

    def billingVersion = 7.0.0

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

}

Step 2: Replace deprecated APIs

• If you’re migrating off of Play Billing Library 5, you might still be using ProrationMode to apply upgrades and downgrades to a user’s subscription status. From PBL 6 onwards, you’ll need to use ReplacementMode instead (find the related API documentation here)
• The following subscription related APIs were previously deprecated, but have now also been removed:
  • setOldSkuPurchaseToken should be updated to setOldPurchaseToken
  • setReplaceProrationMode should be updated to setSubscriptionReplacementMode
  • setReplaceSkusProrationMode should be updated to setSubscriptionReplacementMode
• If you’re currently using pending transactions for consumables, note that there’s no longer an order ID created for pending purchases. Update your billing integration to only expect an order ID after a transaction has been fully completed
• If you’re using the alternative billing APIs, note that those have been renamed. You can no longer use BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener, and AlternativeChoiceDetails, but should use BillingClient.Builder.enableUserChoiceBilling() with UserChoiceBillingListener and UserChoiceDetails instead (no behavior changes)

Step 3: Update Play Billing Library Error Handling (Optional)

If you’ve built custom logic to determine how you respond to billing errors, it’s important to note that BillingResult now includes a new NETWORK_ERROR code which indicates network connection issues, with updates also made to SERVICE_TIMEOUT and SERVICE_UNAVAILABLE. Find more information on billing error handling and the different codes returned by BillingResult here

Step 4: Implement New Subscription APIs (Optional)

Want to use the newly introduced support for pending purchases for prepaid plans or virtual installment subscriptions? Find the guide for pending purchases here, and the guide for installments here

Step 5: Test Thoroughly (NOT Optional)

Before rolling out the update to all users, thorough testing is crucial. Ensure that the new billing flow works seamlessly, subscriptions are managed correctly, and edge cases are handled, especially if you’ve implemented any of the new APIs:

• For installments, it’s currently unclear whether any specific test cases are available. We’ll update this post if and when test cases are published
• For pending purchases, use Google Play’s License testers option to test purchases with a ‘Slow test card’ which will either decline or approve after a few minutes

(The available payment methods for a license tester in Play Console)

For further details on how to properly test your Play Billing Library 7 migration, simply follow the steps detailed in our ultimate guide to Android subscription testing.

RevenueCat’s support for Play Billing Library 7

As detailed in this post, Google Play Billing Library 7 introduces multiple changes compared to previous versions of Billing Library, most notably with the introduction of virtual installment subscriptions and pending purchases for pre-paid subscriptions. Even though most changes are minor, they’ll still require an update and – with that – development time. RevenueCat saves you the hassle and errors that come with migration on your own.

We provide 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, provide clean and consistent data, as well as features that make supporting your customers and growing revenue easier.

Our Android SDK has supported PBL 7 from June 10th, less than a month after this latest version of Google Play Billing Library was presented at Google I/O. Find our Android SDK, including Play Billing Library 7 support, here. 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 7. No need to worry about implementing any of the Billing Library SDK changes: RevenueCat has taken care of all the heavy lifting. 

Useful resources about Billing Library 7 and PBL migration

• Google Play Billing Library 7.0.0 release notes (link)
• Google guide to migrating to Play Billing Library 7 (link)
• Handle subscription pending transactions (link)
• I/O 2024 session “Scale and optimize your business with Google Play” (link)
• Installment subscription integration (link)