Docs
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.
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 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.
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.
Chargebee only supports auto-renewing base plans. Prepaid base plans are currently not supported.
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.
Chargebee only supports free trials. Introductory pricing i.e. single payment upfront and discounted recurring payments are currently not supported.
The enhancements brought by Billing Library 5.0 offer developers a multitude of advantages:
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.
Articles & FAQMonetization.subscriptions to manage subscription products.Monetization.basePlans to manage base plans for subscriptions.Monetization.offers to manage offers for base plans. inappproducts API to manage your in-app product catalog for one-time purchase products.build.gradle file. Post this initialize the billing client and establish a connection to Google Play.SkuDetailsParams with QueryProductDetailsParams.BillingClient.querySkuDetailsAsync() call to use BillingClient.queryProductDetailsAsync(). 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.ProductDetailsParams, instead of using SkuDetails for BillingFlowParamsSubscriptionOfferDetails object to obtain the offer ID, base plan ID, and other offer detailspurchases.subscriptionsv2.get with the purchase token instead of purchases.subscriptions.get.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.
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.
{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 |
|
|
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 |
retrieveProductIdentifiers will return the old product IDs configured in Chargebee.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) |
All the products in Chargebee will be available under the Google Play store product family.
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 |
| 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 |
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
)
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
)
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.
Here are a few limitations that you should make a note of while migrating from the old SDK version to the new SDK version:
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.
API References