Understanding Google Play Billing Library 5

The I/O conference in 2022 brought us a new major version of the Google Play Billing Library. Google added new methods, deprecated and removed some older ones, but most importantly, they introduced a brand new subscription model that should change our ways of working with in-app purchases. 

According to Google’s statements, starting on August 2, 2023, all new apps must use Billing Library version 5 or newer, and by November 1, 2023, all updates to existing apps must use Billing Library version 5 or newer. So if you haven’t yet migrated and want to know more about the new version of Billing LIbrary, let’s get into details and see what it has to offer.

New subscription model: more flexibility, less complexity

The true highlight of the Google Play Billing Library 5 is the renewed subscription model. Google significantly reworked the subscription architecture by adding new entities – base plans and offers. Previously, offers (introductory offer and free trial) were directly tied to the subscription entity, which meant you had to create a new subscription every time you wanted to test a new offer, which wasn’t really convenient. New architecture solves this problem by detaching the offer into a separate entity. This can be very well seen in the illustration:

We can see that the subscription we’re accustomed to now has a more complex, yet more flexible structure. The subscription itself has become a separate core element that consists of base plans, which in their turn can include one or more offers. All the attributes that used to be included in one subscription are now shared within these three entities.

Subscription now only states what benefits the user gets and provides only basic information: identifier, title, description, and taxes info.

The base plan mainly provides information on the billing period and renewal type, which can be auto-renewing or prepaid. But it as well states the grace period and info on the prices and availability for different regions.

Offer acts as an entity that provides additional marketing attributes, like free trial and introductory prices. Here’s where the eligibility comes into play, as offers are available only to the users who meet the eligibility criteria that you personally define. For example, a base plan with a standard monthly subscription is available to anyone, but a monthly subscription offer with a 15% discount is available only to a certain eligible group of people, that you define yourself. Depending on the goal, offers can be divided into:

• The acquisition offers that are based on trials and discounted prices.
• Upgrade/crossgrade offers that help move users to higher tiers or longer billing periods.
• Custom offers where you define the parameters as you wish. Usually used for win-back campaigns, second chance free trials, etc.

Pricing itself gets more flexible as well, with a number of options you can set within an offer:

• Regional availability: specify countries, territories, and pricing for each region. 
• Pricing updates: update the price of your subscription just for new subscribers, leaving the current ones unaffected to this. 
• Prepaid plans: price prepaid plans with top-ups, which is useful for countries and regions where pay-as-you-go is standard.

To sum it up, users now purchase a base plan or an offer to gain access to the subscription, instead of just purchasing a subscription. If it still sounds confusing, let’s have a look at the example:

For a standard three-product paywall you had to have three separate subscriptions, for example weekly, monthly, and annual. Let’s say the weekly subscription had just a standard price, the monthly one offered a free trial, and the annual option also offered the trial along with a discount. But imagine that you had a cohort of monthly subscribers that you wanted to upgrade to the annual subscription by offering a higher discount for a limited amount of time. In this case, you had to create a whole new annual subscription product with the desired parameters, because all the attributes belonged to the subscription entity.

If you transfer the same paywall to the new subscription model, you’ll have only one subscription entity split into three base plans: weekly, monthly, and annual. And then two of these plans will have additional offers: monthly plan will have a free trial offer, and the annual – offer with a free trial and a discount. So if you want to present the cohort of monthly users with a higher discount for the annual subscription, all you have to do is add another offer to the already existing base plan. It’s a really basic example, but it very well illustrates the working mechanism of the new model.

This approach should ease the developer’s headache of creating a new subscription entity each time they want to test a new offer and make the testing process more flexible in general. 

Creating subscription products in Billing Library 5

The new subscription structure brought changes to the flow of creating products in the Google Play Console. Previously, developers had to create separate subscriptions for each unique combination of benefits, billing periods, and discounts. However, with the new architecture, developers can flexibly define subscription plans with varying benefits and pricing options. Here’s a quick step-by-step guide:

Switch to your developer account and choose the app.

Then, in the menu on the left, find the Products section, select Subscriptions, and click Create subscription. 

In the subscription creation window, specify the Product ID and the Name of your subscription.

When the subscription is created, you can edit its ID and name or add more information by clicking Edit subscription details.

Put down a few words about your subscription in the Description field – this may help you easier navigate between different subscriptions in the future. Click Save changes when you’re done.

So now let’s create and configure a base plan. Go to the Subscriptions section and hit Add base plan at the bottom of the page.

Here you should name your plan ID, select the type of the base plan (Auto-renewing in our case), set the desired billing and grace periods, as well as specify how plan changes should be dealt with.

Scroll down to the Price and availability section and click Set prices. In the pop-up window set the price and the currency of your subscription. Note, that the price will automatically apply to the selected countries and regions. It’s also handy that Google shows the tax for every country.  

Now that the base plan is created, let’s add an offer. Go back Subscriptions, find the Base plan and offers section, and click Add offer.

In the pop-up window, select the base plan you want to add the offer to.

Next, in the offer-editing menu, set the offer ID and select the eligibility criteria that fit your offer. When it’s done, you can go on and configure the price phases by clicking Add phase down below.

Phases were introduced to make the offers more flexible in terms of pricing. You can add up to 2 phases that should be sequentially received by the subscriber. For example, you can select a free trial and add a discounted recurring payment as a bonus that will be activated by the end of the trial.

Click Apply, save all the changes for the product, and that’s it. You may check our more detailed documentation if you still have some questions.

Play Billing Library 5 in-app messaging 

In-app messaging is another interesting feature introduced by Google that’s supposed to help you retain your subscribers with the declined payment. With the help of the in-app messaging API, the users, whose payment gets declined, will see a message reminding them to update their payment info. According to Google, this approach showed a 2x increase in user recovery, as well as growth in overall subscriber spend.

Google Play Billing Library 5.0 backward compatibility

Google Play Console started working with the new version of the subscription model right after the announcement, which meant that all of the old subscriptions were automatically converted to the new format. But they were still working properly, as Google had made them backward compatible. You could still view them in your console but they were displayed with the new structure (subscription, base plans, offers). However, they were made read-only, which meant you couldn’t edit them if you wanted everything to work fine.

Before editing your subscriptions in the Console, Google recommends you to update your backend integration to use the new Subscription Publishing endpoints, such as: monetization.subscriptions, monetization.subscriptions.baseplans, and monetization.subscriptions.offers. You can read more about this and other technical aspects of the May update in the official documentation.

Remarkable technical updates

Several notable changes have been made in the Play Billing Library 5 in terms of code, so let’s highlight them:

• SkuDetails class has been deprecated. Instead, Google suggests using ProductDetails that contains information about the subscription, its base plans, and offers. You can find more details about the migration here.

• launchPriceChangeFlow has also been deprecated and will be removed in the future. Here’s more information on how to do without it.
• Added BillingClient.queryProductDetailsAsync() to replace BillingClient.querySkuDetailsAsync().
• The queryPurchases method has been removed. 
• The setIsOfferPersonalized() method has been added. It’s required to show a personalized price for EU clients on the Google Billing purchase screen.

Adding the Billing Library to a project will now looks like this:

implementation "com.android.billingclient:billing:6.0.1"

At the time of writing, the latest version is 6.0.1. You can replace it with any other version higher than 5.0.

Adapty support and updates

Sometime after the announcement of the Billing Library 5.0, Google made a statement that starting on August 2, 2023, all new apps must use Billing Library version 5 or newer. It wasn’t out of the blue, as in 2019 they announced that all versions of Play Billing Library will follow a two-year deprecation cycle. 

So, with the release of Adapty SDK version 2.6.1, we are happy to say that Adapty now has the full support of Google Billing Library 5 and 6. This update includes several improvements and additions to the public API for the native Android, Flutter, and React Native SDKs. 

Here are a few notable changes:

1. Unified subscription details: We have removed separate properties for free trials on Android to provide a more streamlined experience. Instead, we have introduced an optional subscriptionDetails property that consolidates all subscription-related properties. It includes an introductoryOfferPhases property, which is a list that can contain up to two phases: the free trial phase and the introductory price phase.
2. Payment mode for discounts: To align with iOS, we have added the paymentMode property to the AdaptyProductDiscountPhase entity.
3. Renewal type for subscriptions: We have introduced the renewalType property in the AdaptyProductSubscriptionDetails entity to accommodate the two types of subscriptions available on Google Play: auto-renewable and prepaid.
4. Price entity updates: The price, localizedPrice, currencyCode and currencySymbol properties have been moved from AdaptyPaywallProduct to a new entity called Price.
5. SKU details update: The skuDetails property in AdaptyPaywallProduct has been renamed to productDetails to reflect the use of original product entities from Google.

Find the full list of changes and improvements in our documentation on migration to Google Billing Library v5+.

Unlock 2024 subscription holiday secrets

Discover why apps thrive during Black Friday, Christmas & New Year and how you can do the same.

Get your free report