Docs

Chargebee's Solution for Implementing Billing Library 5.0 

This feature is in BETA. Please contact support  for any query.

Welcome to the comprehensive guide for upgrading and leveraging the functionalities of Google's Billing Library 5.0 within your Android application.

Understanding Google Billing Library 

Google's billing library facilitates communication with Google Play Services to enable localized product offerings and methods to handle user operations, like launching the purchase flow and handling outcomes. Integrating Google Play's billing library with your Android app, enables you to sell digital products and content in your Android app. Learn more

Google announces changes to its library every year and they support the previous versions for at least 2 years after a new release.

Google Billing Library 5.0 Changes 

Google allows to associate only one base plan with a subscription before the I/O 2022 announcement. This meant that app developers had to create a new subscription plan for every offer that was introduced. With the announcement of Billing Library 5.0 in May 2022, Google changed the structure of the subscription product and allowed multiple base plans to be associated with a subscription in the Google Play console.

Exploring New Subscription Structure 

The revised subscription structure introduced by Billing Library 5.0 comprises three fundamental elements: Subscriptions, Base Plans, and Offers. These components collectively redefine the way developers configure and offer subscription services to end-users. Learn more about the new subscription product structure.

  • Subscription: A subscription is a set of benefits that users can access during a stated time period. From the app developer's perspective, it is a distinct digital service sold to end users. For instance, an app can sell platinum, gold, and silver subscription tiers with each of these subscriptions having a distinct set of benefits for its end users. Other examples stated by Google include a streaming video app selling separate "news" and "sports" subscriptions or a cloud storage app selling 100 GB, 1 TB, and 10 TB subscriptions. Users gain access to a subscription by purchasing a base plan or offer associated with a subscription
  • Base plan: Subscriptions contain one or more base plans. The billing or subscription renewal period and the region-specific pricing for subscription products are configured as part of base plans. You can also specify whether a subscription renews automatically (auto-renewing) or is non-renewing (prepaid plan). Multiple base plans with different billing frequencies and pricing can be associated with a subscription plan. As an example, for a single "Gold Membership" subscription, you could create the following base plans:
    • A half-yearly, auto-renewing base plan.
    • A monthly, auto-renewing base plan.
    • A monthly, prepaid base plan.
    • An annual, auto-renewing base plan.
Note

Chargebee only supports auto-renewing base plans. Prepaid base plans are currently not supported.

  • Offers: Base plans can be associated with multiple offers. Offers allow users to purchase plans at discounted prices. There are three types of offers that can be configured in the Play Store and Google terms these as offer phases:
    • Free trial: Users can access the service free for a specified limited time period
    • Single payment upfront: Users pay a discounted price upfront only once and get access to the service for a specified limited time period. Post this period users will be automatically charged the regular subscription price
    • Discounted recurring payment: Users pay a discounted price for a specified number of subscription renewals (that can be between 1 to 52) and thus get access to the service at a discounted price during this period. Post this period users will be automatically renewed at the regular price.

The eligibility criteria of these offers are also configurable. So the discounted price or free trials can be offered either for new users to increase acquisitions or for existing users to achieve retention goals. There's also an option for the developer to determine the eligibility criteria and in this case, it is up to the app developer to determine the user's eligibility for a given offer.

Note

Chargebee only supports free trials. Introductory pricing i.e. single payment upfront and discounted recurring payments are currently not supported.

Benefits of Embracing the New Subscription Structure 

The enhancements brought by Billing Library 5.0 offer developers a multitude of advantages:

  • Flexibility to create different offerings
    • As multiple base plans can be associated with the same subscription, there's no need to create multiple subscriptions in the Google Play console to offer a combination of benefits, billing periods, and discounts.
    • Provision to associate pre-paid base plans along with auto-renewable plans to a single subscription, allows developers to offer the same service in different pricing models in different regions.
    • Offer phases can be used to create offers with discounts or free trials or a combination of free trials and discounted prices
    • With developer-determined offer functionality, eligibility criteria can be added at the app level on top of Play-evaluated eligibility criteria to decide the best possible offer
  • Pricing experiments
    • Pricing and availability of service can be easily controlled for different regions as base plans and prices can be configured for specific regions or countries
    • Pricing of base plans can be changed and the plans can be de-activated or activated at any point of time without affecting the subscription. This makes it easier to manage price changes.
    • Tags can be added to a plan to identify the base plan or the offer in the API. They can be used to determine which offer to show when the user is eligible for more than one offer.
    • The same product can be sold with different offers to determine the offers that work the best in the market or region.

Migration from Billing Library 4.0 to 5.0 

Google's Approach 

In case you're not using Chargebee's SDKs then migrating from billing library 4.0 to 5.0 will involve multiple steps. Here's a brief step-by-step guide for this migration.

  • Create a new subscription product catalog: Google recommends creating new products following the new entity structure, as editing backward compatible old products can result in issues with older versions of the app that may use deprecated methods like querySkuDetailsAsync(). To do this, consolidate duplicate products in your old catalog representing the same entitlement benefits under a single subscription and use base plan & offer configurations to represent all the options that you want to offer.
  • Manage catalog with the new APIs: Migrate product catalog management in Google Play Billing subscriptions by replacing the old InAppProducts API with the new Subscription Publishing API. These are the three new endpoints that you need to implement:
    • Monetization.subscriptions to manage subscription products.
    • Monetization.basePlans to manage base plans for subscriptions.
    • Monetization.offers to manage offers for base plans.
      You should still use the inappproducts API to manage your in-app product catalog for one-time purchase products.
  • Update the billing library dependency: Replace the existing Play Billing Library dependency with the updated version of your app's build.gradle file. Post this initialize the billing client and establish a connection to Google Play.
  • Show products to buy: As Google has switched from SKUs to products, the calls required to display products or offers have changed.
    • Replace SkuDetailsParams with QueryProductDetailsParams.
    • Switch the BillingClient.querySkuDetailsAsync() call to use BillingClient.queryProductDetailsAsync().
      Query results are now ProductDetails instead of SkuDetails containing the information about the product (ID, title, type, and so on). For subscription products, ProductDetails contains a List<ProductDetails.SubscriptionOfferDetails>, which has the list of all base plans and offers to be presented to the end user.
  • Launch the purchase flow: Purchase flow can be launched by selecting the specific offer to be applied to the user
    • Use ProductDetailsParams, instead of using SkuDetails for BillingFlowParams
    • Use SubscriptionOfferDetails object to obtain the offer ID, base plan ID, and other offer details
  • Processing purchases: To pull all active purchases owned by the user and query for new purchases pass a QueryPurchasesParams object that contains a BillingClient.ProductType value instead of passing a BillingClient.SkuType value to queryPurchasesAsync().
  • Managing subscription purchase status: Implement the Subscription Purchases API for real-time subscription purchase status management. Replace calls to purchases.subscriptions.get with the new purchases.subscriptionsv2.get for more comprehensive subscription status information using the resource SubscriptionPurchaseV2.
  • Real-time developer notifications: The Pub/Sub payload for real-time purchase notifications no longer includes subscriptionId. To check subscription status, use purchases.subscriptionsv2.get with the purchase token instead of purchases.subscriptions.get.

Chargebee's Approach 

Chargebee's backend and Android SDKs support billing library 5.0, so upgrading becomes easier as you don't need to worry about Play Store API changes. Here are the steps that you need to follow for this migration.

  • Enable Billing Library 5.0 support for your Chargebee site: Please contact support to enable the billing library 5.0 for your Chargebee site. Enabling this setting will allow you to import products with multiple base plans and offers from Google to Chargebee.

Example:
When a gold membership plan has product ID gold and there are two base plans with IDs: half-yearly and monthly associated with this product, then earlier only one plan ID i.e. gold was created post import. Once this setting is enabled, two new plans i.e. gold-half-yearly and gold-monthly will be created in Chargebee.

  • Create a new product catalog in the Google Play Console: As recommended by Google, Chargebee insists on creating a new product catalog in the Google Play Console by consolidating duplicate products in your old catalog that represent the same entitlement benefits under a single subscription.
Note
  • While creating a new product catalog make sure that the combination of product ID and base plan ID doesn't exceed 95 characters limit.
  • Though it is recommended by Google it is not a mandatory step for Chargebee. Even if you don't create a new product catalog, Chargebee will import the old products with a default backward compatible base plan in the new format (i.e. for the sites using product catalog V1, the plans would be created in format {ProductId}-{basePlanId}-{CurrencyCode} and for the sites using product catalog V2 the format will be {ProductId}-{basePlanId})

For instance, if there were 12 products earlier in Google and each product had a backward compatible plan associated with it then, the old product catalog would look like

S.No.

Product ID

Backward compatible base plan ID

Backward compatible base offer ID

1.

platinum

half-yearly

1-month-free-trial

2.

platinum_2

half-yearly

1-week-free-trial

3.

platinum_3

monthly

1-month-free-trial

4.

platinum_4

monthly

1-week-free-trial

5.

gold

half-yearly

1-month-free-trial

6.

gold_2

half-yearly

1-week-free-trial

7.

gold_3

monthly

1-month-free-trial

8.

gold_4

monthly

1-week-free-trial

9.

silver

half-yearly

1-month-free-trial

10.

silver_2

half-yearly

1-week-free-trial

11.

silver_3

monthly

1-month-free-trial

12.

silver_4

monthly

1-week-free-trial

Post consolidation, the new product catalog in Google will look like this:

S.No

Product ID

Base Plans

Offer ID

  1.  

platinum

half-yearly

1-month-free-trial

1-week-free-trial

monthly

1-month-free-trial

1-week-free-trial

2. 

gold

half-yearly

1-month-free-trial

1-week-free-trial

monthly

1-month-free-trial

1-week-free-trial

3.

silver

half-yearly

1-month-free-trial

1-week-free-trial

monthly

1-month-free-trial

1-week-free-trial

  • Import new products to Chargebee: Import the new product catalog configured in the Google Play console to Chargebee. Here's the link that will guide you on importing Play Store products to Chargebee.
Note
  • Chargebee imports product IDs from the Google Play console as a combination of product ID and base plan ID to support the new subscription product structure specified by google billing library 5.0. The character limit for this combination is 95 in Chargebee.
  • You can create new product catalog in google play console by consolidating all the base plans and offers under an existing product ID or use new product ID. In either of these cases, post import, all these products will be created newly while the old products continue to exist in Chargebee.
  • Chargebee retains the old products, as this will allow you sometime to migrate all users to new version of App that uses latest SDK. For users who haven't upgraded to the new version of app that uses latest SDK, Chargebee will continue recording subscriptions with old product format.
  • If you're force upgrading all users to new version of app and want to present only new product catalog for purchases, then it is recommended to import only new products to Chargebee by deactivating the base plans associated with old product IDs in Google.
  • Post import of new products, it is needed to move all the existing subscriptions in Chargebee to new product IDs and deactivate all the old products. By doing this there will be no duplicate products in Chargebee and all the subscriptions will be associated with the new product catalog.
  • To move existing subscriptions in Chargebee to new products, you need to present a mandatory option to users who migrated to new version of app, to select a product that belongs to the new product catalog. As soon as the user upgrades to the latest version of the app, Chargebee will receive an upgrade notification and move user to the new product.
  • If new product catalog is not created in the Google Play Console or the new products are not imported to Chargebee then SDK method retrieveProductIdentifiers will return the old product IDs configured in Chargebee.
  • You can still use the latest SDK method retrieveProducts with these product identifiers to retrieve the product, base plan and offer information and make a purchase. In this case, during purchase Chargebee will automatically create a new product as a combination of product ID & base plan ID and associate subscription with this new product.

Let's consider the same example as mentioned in the previous step. Now if both old and new products have active base plans in Google and the re-import is attempted in Chargebee for all these products then the product catalog in Chargebee will look like this:

S. No.

Product ID

Old / New Product Catalog

1

platinum

Old product (Already existed in Chargebee)

2

platinum_2

Old product (Already existed in Chargebee)

3

platinum_3

Old product (Already existed in Chargebee)

4

platinum_4

Old product (Already existed in Chargebee)

5

platinum-half-yearly

New product (Created from new catalog)

6

platinum-monthly

New product (Created from new catalog)

7

platinum_2-half-yearly

New product (Created as old product is active in google)

8

platinum_3-monthly

New product (Created as old product is active in google)

9

platinum_4-monthly

New product (Created as old product is active in google)

10

gold

Old product (Already existed in Chargebee)

11

gold_2

Old product (Already existed in Chargebee)

12

gold_3

Old product (Already existed in Chargebee)

13

gold_4

Old product (Already existed in Chargebee)

14

gold-half-yearly

New product (Created from new catalog)

15

gold-monthly

New product (Created from new catalog)

16

gold_2-half-yearly

New product (Created as old product is active in google)

17

gold_3-monthly

New product (Created as old product is active in google)

18

gold_4-monthly

New product (Created as old product is active in google)

19

silver

Old product (Already existed in Chargebee)

20

silver_2

Old product (Already existed in Chargebee)

21

silver_3

Old product (Already existed in Chargebee)

22

silver_4

Old product (Already existed in Chargebee)

23

silver-half-yearly

New product (Created from new catalog)

24

silver-monthly

New product (Created from new catalog)

25

silver_2-half-yearly

New product (Created as old product is active in google)

26

silver_3-monthly

New product (Created as old product is active in google)

27

silver_4-monthly

New product (Created as old product is active in google)


In case, only new products have active base plans in Google and the base plans associated with old products are deactivated the post-re-import product catalog in Chargebee will look like this:

S.No.

Product ID

Old / New Product Catalog

1

platinum

Old product (Already existed in Chargebee)

2

platinum_2

Old product (Already existed in Chargebee)

3

platinum_3

Old product (Already existed in Chargebee)

4

platinum_4

Old product (Already existed in Chargebee)

5

platinum-half-yearly

New product (Created from new catalog)

6

platinum-monthly

New product (Created from new catalog)

7

gold

Old product (Already existed in Chargebee)

8

gold_2

Old product (Already existed in Chargebee)

9

gold_3

Old product (Already existed in Chargebee)

10

gold_4

Old product (Already existed in Chargebee)

11

gold-half-yearly

New product (Created from new catalog)

12

gold-monthly

New product (Created from new catalog)

13

silver

Old product (Already existed in Chargebee)

14

silver_2

Old product (Already existed in Chargebee)

15

silver_3

Old product (Already existed in Chargebee)

16

silver_4

Old product (Already existed in Chargebee)

17

silver-half-yearly

New product (Created from new catalog)

18

silver-monthly

New product (Created from new catalog)


If you have decided to use only the new products for all your app users and force upgraded all your users to new products, deactivated the base plans associated with the old products in Google, and requested Chargebee support to deactivate the old products, then active product catalog in Chargebee will look like:

S.No.

Product ID

Old / New Product Catalog

1

platinum-half-yearly

New product (Created from new catalog)

2

platinum-monthly

New product (Created from new catalog)

3

gold-half-yearly

New product (Created from new catalog)

4

gold-monthly

New product (Created from new catalog)

5

silver-half-yearly

New product (Created from new catalog)

6

silver-monthly

New product (Created from new catalog)

Note

All the products in Chargebee will be available under the Google Play store product family.

  • SDK implementation: Upgrade your App to the latest version of Android, React Native, or Flutter SDKs that use billing library 5.0 APIs to retrieve product details and make a purchase. Below points need to be noted while implementing SDKs in your app.
    • Implementation of retrieveProductIdentifiers method: This method will return the unique product identifiers for all the products imported from Google to Chargebee.
Note

In case old products are not deactivated, then same product will exist in old and new format in Chargebee, but retrieveProductIdentifiers method of the latest SDK will return only the unique product IDs. So if there are ‘gold' and ‘gold-monthly' products present in Chargebee, then this method will return only the product ID 'gold' as this is the only product present in google play store.

In case you are using the older version of SDK, then this method will return all the products present in Chargebee. So if there are ‘gold' and ‘gold-monthly' products present in Chargebee, then this method will return both gold and gold-monthly. App developers should make sure that the correct product ID is passed at the time of purchase. To avoid writing this extra logic at app end, we recommend to use the latest version of the SDK.

Considering the same example, product IDs returned by retrieveProductIdentifiers of SDK 2.0 will be

S.No.

Product IDs Returned by retrieveProductIdentifiers

1

platinum

2

platinum_2

3

platinum_3

4

platinum_4

5

gold

6

gold_2

7

gold_3

8

gold_4

9

silver

10

silver_2

11

silver_3

12

silver_4


  • Implementation of retrieveProducts method: Earlier this method was used to return only the product and backward compatible base plan information. Now retrieveProducts method will return the product ID, base plan ID, and offer ID corresponding to the product IDs for which this method is invoked. So the app should consume this information and display the product(s) and offer(s) that are most relevant to the end user.
Note

While using SDK 2.0, App developers should make sure that they pass product IDs corresponding to the new catalog though Chargebee returns all the product IDs present in the store. This will make sure that purchase is associated with the new plan.

In case, the old product ID is passed and this is not active in play store then Chargebee will return an empty array response. If the old product is passed and active in the play store then Chargebee will return the corresponding product, base plan & offer information. During purchase, this old product will be imported to Chargebee in the new format (if not already imported) and subscription will be associated with this newly imported product.

As the response of this method is changed, App developer should make changes at app end to handle the new response format.

Here's the input and response format of retrieveProducts method of Android SDK 2.0 for active products configured in the google play console.

Request format:


Activity // Current activity
ArrayList<String>, // List of product identifiers
ListProductsCallback // Callback

interface ListProductsCallback<T> {
    fun onSuccess(productIDs: ArrayList<CBProduct>)
    fun onError(error: CBException)
}

Repsonse format:


// CBProduct format 
data class CBProduct(
    val id: String,
    val title: String,
    val description: String,
    val type: ProductType,
    val subscriptionOffers: List<SubscriptionOffer>?,
    val oneTimePurchaseOffer: PricingPhase?,
)

data class SubscriptionOffer(
    val basePlanId: String,
    val offerId: String?,
    val offerToken: String,
    val pricingPhases: List<PricingPhase>
)
data class PricingPhase(
    val formattedPrice: String,
    val amountInMicros: Long,
    val currencyCode: String,
    val billingPeriod: String? = null,
    val billingCycleCount: Int? = null
)


  • Implementation of purchaseProduct method: Earlier the input parameter for this method was only the product ID. Now App needs to pass the product ID and offer ID details of the selected product so that the value of billingFlowParams can be set while invoking the new launchBillingFlow method of Billing client library 5.0. The response of this method will remain the same and this will be the in-app subscription object with subscription ID, product ID, and customer ID.
Note

When purchaseProduct is invoked for a product ID (active in the store) but not yet imported to Chargebee, then Chargebee will auto-import the product by fetching the base plan information at the time of purchase and associate the subscription with this newly imported product.

Here's the sample input and response format of purchaseProduct method of Android SDK 2.0

Request format:


PurchaseProductParams,
CBCustomer,
PurchaseCallback

data class PurchaseProductParams(
    val product: CBProduct,
    val offerToken: String? = null
)

data class CBCustomer(
    val id: String?,
    val firstName: String?,
    val lastName: String?,
    val email: String?
)

interface PurchaseCallback<T> {
    fun onSuccess(result: ReceiptDetail, status: Boolean)
    fun onError(error: CBException)
}

Response format:


// ReceiptDetail
data class ReceiptDetail(
    val subscription_id: String, 
    val customer_id: String, 
    val plan_id: String
)
Note

retrieveAllItems or retrieveAllPlans will return all the items or plans that are active in Chargebee. So these methods should be used only to find out the plans information in Chargebee and not for identifying the products configured in Google Play console. To identify the products configured in Google Play console use the method retrieveProductIdentifiers.

Limitations 

Here are a few limitations that you should make a note of while migrating from the old SDK version to the new SDK version:

  • Product ID and base plan ID combination cannot be more than 95 characters in the Google Play console, as Chargebee uses this combination along with currency code and hyphens to create a corresponding plan ID that has a limit of 100 characters.
  • Duplicate products will be present in Chargebee unless all subscriptions are migrated to a new product ID format. This is done to make sure that you get enough time to migrate all your users to a new app version. Once all users are migrated to the new app version, and their subscriptions are updated to new product IDs, old products in Chargebee can be deactivated by raising a request to support.
  • Unless all existing subscriptions are migrated to the new product ID format, they will continue to renew on old product IDs in Chargebee and thus Revenue Story or downstream analytics will report this revenue with old product IDs
  • Chargebee supports only free trial offers. So other offer phases i.e. single payment upfront and discounted recurring payment are not supported by Chargebee. If these offer phases are configured in the Google Play console then Chargebee will record the subscription at a discounted price and the subscription will renew at the discounted price.
  • There's no SDK method for handling upgrades and downgrades. So the app needs to handle this logic by presenting the appropriate plans & offers to end users for upgrade/downgrade.
Note

Google allows users to switch between subscription products as well as between base plans configured within a subscription product. Thus users can either switch subscription tiers or change their billing frequency by switching to different base plans. Learn more.

In all these cases i.e. upgrade, downgrade, or subscription change, google sends server notifications through the topic ID and Chargebee listens to these notifications to update the subscription state accordingly. Learn more.

  • Chargebee supports only the default proration mode specified by Google i.e. IMMEDIATE_WITH_TIME proration and this is the same as the new replacement mode specification WITH_TIME_PRORATION. As per this proration mode, subscriptions are immediately upgraded or downgraded and any time remaining in the current term is adjusted (i.e. reduced from or added to the current term) based on the price difference. The next billing date for the upgraded/downgraded plan is decided based on the current term adjustment.
  • Chargebee supports only base plans of type 'Auto-renewing'. Base plans of type 'Prepaid' are not supported currently.
Was this article helpful?
Loading…