Chargebee's Solution for Implementing Billing Library 5.0 

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 allowed 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.

• 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.

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 initialise 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.

• 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.

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

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

• 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.

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:

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:

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:

• 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.

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

• 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.

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.

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
)

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.

• 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.