The final countdown: the mandatory migration to Google Play Billing 5 and 6

In May 2022, Google did it again… And you’ll have to do it again, too!

The fresh face in the brand’s lineup for In-App billing and subscriptions, Google Play Billing Library 5 came with a suite of features and upgrades that promise a smoother In-App Purchase experience for your users and a smarter revenue generation experience for your app. 

These updates aren't the only reason to think about leaving the v4 behind.

• As of August 2023, any newly launched apps will no longer have the liberty to incorporate Play Billing Library 4.
  
  
• By November 2023, app updates will also be restricted from employing Play Billing Library 4.

 (Read more from Google)

Historically, getting all the developers to stay on the side of innovation was a challenge. But with this timeline, we should see some more motivation or at least pressure.

But we've got you covered. Everything you need for a safe migration? It's ready with Purchasely's support for Google Billing V5.

Read on!

Table of contents

• Google Play Billing Library 5 updates: What subscription apps need to know

  - New subscription architecture

  - Flexible pricing

  - Optimized user purchase outcome management

  - Backend updates

• Migrating to Google Play Billing Library 4 to 5: Hidden challenges

• Adopt Purchasely to migrate effortlessly

Google Play Billing Library 5 updates: What subscription apps need to know

Here's a breakdown of what’s noteworthy for apps with subscriptions and/or In-App Purchases. 

'Migrate to Billing Library 5' - Introduction to Google Play Billing 5 at android dev summit

The new subscription architecture

Image source: Google

• Subscriptions: Represents what's being sold to users, including the product and its benefits.

• Base plans: Covers how it's sold, detailing whether it's an auto-renewable or a prepaid plan, its duration, and the base price.

• Offers: Modifications made to the base price, such as free trials or introductory prices, with developers determining eligibility criteria.

2. Flexible pricing

• Dynamic pricing: As users journey through their subscription, the pricing phases will offer varied prices, allowing for promotional periods, discounts, or tiered pricing, increasing the appeal for users to stay subscribed or even upgrade.
  
  Google is finally matching what Apple was offering with its Subscription offers but even more as they can tailor offers to new subscribers.
  
  ▶️ Marketing implication: Retention and Win-back offers can now be available in both stores in a symmetrical way. This will double the reach of these offers but also provide a way to distribute offers evenly and make your campaigns more readable.
  
  
  
• Refined region-specific pricing: Developers can set prices for each region or provide a universal price, leaving Google to handle the one-time currency conversion for the selected areas.
  
  ▶️ Marketing implication: With flexible pricing, marketers can deploy time-sensitive promotions or loyalty incentives, capturing a wider audience. Region-specific strategies enable a global reach with localized appeal.

3. Optimized user purchase outcome management 

• Enhanced purchase tracking: With the introduction of queryPurchasesAsync, developers can now more accurately track and manage user purchases.

  ▶️ Enhanced purchase visibility allows marketers to build post-purchase engagement strategies, fostering loyalty and repeat business while simultaneously minimizing customer support demands.

4. Backend updates for future-proofing

• Streamlined subscription status retrieval: The new subscriptionPurchasedV2 endpoint allows for a more efficient way of fetching subscription statuses.

• Granular purchase insights: The subscriptionPurchases.subscriptionsV2 entity offers detailed insights into every purchased item.

  
  ▶️ This means developers can understand user behavior at a micro-level, tweaking offers and strategies based on real-world data.

Migrating from Google Play Billing Library 4 to 5: Hidden challenges

The migration to version 5 requires a series of steps that can be avoided if you are already monetizing your app with Purchasely. If that is the case, update to the latest Purchasely 4.x SDK version and you are good to go.

The full migration steps are provided by Google here.

While migrating to Google Play Billing v.5, you will come across several challenges.

Here are some major issues, including those that Google hasn’t clearly addressed:

1. Setting up your product catalog all over again

Google suggests you start over with your products using PBL5 before updating your app. This means merging similar products with different prices or durations. And doing it wrong? Your app on PBL4 might break.

2. Handling the new API 

Up until GB4, you could retrieve active subscription details using the purchases.subscription.get endpoint.

Since GB5 and its revamped product/base plan configuration, the new purchases.subscriptionsv2.get endpoint is needed to query subscriptions (One-time purchases remain unaffected).

In its May 2022 subscription changes guide, Google highlighted the main differences between the APIs and which properties were mapped from, to, or moved to a completely different API. 

Below, we highlight the hidden challenges that will be encountered when migrating to the new API:

Price and offer tracking

• ⏱ In the past: Price information was available directly in the priceCurrenceCode, priceAmountMicros, introductoryPriceInfo fields of purchases.subscription, which helps to know if the subscription started with a trial/intro period or not and at what price.

• 🆕 Now: This information is no longer available directly.

• 🏋 Challenge: Two new endpoints monetization.subscriptions and monetization.subscriptions.basePlans.offers have been introduced to track base plan pricings and offer pricing separately. There's no way to retrieve the history of these changes. For instance, you can't determine the exact price at which a subscription was bought, or if it had a trial and/or introductory offer associated.

  In addition, those endpoints do not list the configuration associated with countries that are subdivisions, whereas regionCode can be associated with a subdivision:
  

  • If regionCode is PR (Puerto Rico), look for prices the United States (US) region

  • More subtle, if regionCode is FO (Faroe Islands), look for prices in Denmark (DK) region

   

  ▶️  How Purchasely helps: For each purchase, Purchasely helps query the new endpoints, maintain a history of prices, offers, and durations. We recommend useing the Google Play Support Page to retrieve the actual associated country if regionCode denotes a subdivision before querying the base plans / offer endpoints.

Promo code tracking

• ⏱ In the past: promotionType, promotionCode fields of purchases.subscription were available directly.

• 🆕 Now: There is no equivalent to these fields (anticipated to be available soon).

• 🏋 Challenge:  As of September 2023, it's unclear if a subscription was granted using a promotional code by just using purchases.subscriptionsv2.

  ▶️ How Purchasely helps: Purchasely helps query both SubscriptionPurchase and SubscriptionPurchaseV2. The former has the property to identify promotional code usage, while the latter determines the correct plan linked to the subscription. But, querying both might double your quota usage with Google, risking quota exceedance.

  For now, only the Backwards compatible plan (a plan that can be purchased from the older GPBL4) can be associated with promo codes when creating a promo code from the Google Play Console.

  We anticipate other base plans becoming available once Google adds the missing fields.

Identifying active subscriptions made before May 2022

• 🆕 Now: The field lineItems.offerDetails.basePlanId (or even the entire offerDetails field) might be missing for active subscriptions that existed before May 2022.
  
  
• 🏋 Challenge: As you migrate the configuration of your plans in your infrastructure and expect to match an active subscription not just with the subscriptionId field (which is now renamed productId), but with the combination of productId:basePlanId, you will not be able to find to which plan the subscription belongs to as it is missing the basePlanId field.
  
  ▶️ Our advice: If the field is absent, it indicates that the subscription was active before May 2022. It's likely linked to the backward-compatible base plan associated with the subscription productId, assuming that the plan has never been changed.
  
  
  
  Don't modify the backward-compatible plan in the Play Console unless you're already tracking changes made to basePlans internally or you're certain there are no active subscriptions remaining on that plan.
  
  

Adopt Purchasely to migrate effortlessly

Scratching your head over the migration? Let Purchasely step in to help you escape the maze of updates and adaptations.

Why choose Purchasely?

• Simplified migration: Purchasely eliminates the complexities of adapting to Google Play Billing v.5 and beyond. Our platform ensures a smooth transition without the challenges typically faced during such migrations.
  
  
• Expert guidance: Our dedicated customer success and solutions engineering teams are always ready to guide you through the migration process, ensuring it's smooth and error-free.
  
  
• Stay updated without the hassle: As billing systems constantly evolve, it's vital to stay updated. With Purchasely, you're always ahead, as we automatically incorporate new features and changes: v5, v6 and beyond. You will never have to worry about all this and most importantly you will benefit from all the features (Such as integrating Promotional Offers) that are directly actionable. 
  
  
  
• Cost-efficient: Transitioning to a new billing system can lead to unexpected costs due to errors, delays, or missed opportunities. With our streamlined process, you save both time and money.
  
  
  

Ready to make the switch?

Migrating to Google Play Billing v.5 and v.6 doesn't need to be intimidating. With Purchasely, you can ensure your app's billing system remains updated without the typical hassles.

Discover how Purchasely can enhance your app's billing system.

Book a 1:1 chat with us now to learn more about our comprehensive migration solutions and elevate your app's potential.