Migrate to Google Play Billing Library 7 from versions 5 or 6

This document describes how to migrate from Google Play Billing Library 5 or 6 to Google Play Billing Library 7 and how to integrate with the new optional subscription capabilities.

For a full list of the changes in version 7.0.0, refer to the release notes.

Overview

Google Play Billing Library 7 improves payment handling for existing subscription features. These optional improvements add support for paying with installment plans as well as support for pending purchases for prepaid subscriptions.

Backward-compatible Play Billing Library upgrade

All new Google Play Billing Library 7 APIs are optional, and developers don't need to implement any API changes to update.

To migrate, you need to update API references and remove certain APIs from your app as described in the release notes and later in this migration guide.

Upgrade from PBL 5 to PBL 7

The following sections describe how to upgrade from PBL 5 to PBL 7.

Update Google Play Billing Library

Update the Play Billing Library dependency version in your app's build.gradle file.

dependencies {
    def billingVersion = 7.0.0

    implementation "com.android.billingclient:billing:$billingVersion"
}

Next, update your API references as described in the following sections.

Change a user's subscription purchases

Play Billing Library 5 and earlier used ProrationMode to apply changes to a user's subscription purchases, such as upgrades or downgrades. This API has been removed and replaced with ReplacementMode.

Handle subscription price changes

The previously deprecated launchPriceConfirmationFlow API has been removed. For alternatives, see the price changes guide.

Handle subscription related API changes

The previously deprecated APIs setOldSkuPurchaseToken, setReplaceProrationMode, setReplaceSkusProrationMode have been removed.

Handle Play Billing Library errors

A new NETWORK_ERROR code indicates problems with the network connection between the user's device and the Google Play system.

The SERVICE_TIMEOUT and SERVICE_UNAVAILABLE codes were also updated.

For more information, see Handle BillingResult response codes.

Handle pending transactions

The Play Billing Library no longer creates an order ID for pending purchases. For these purchases, the order ID is populated after the purchase is moved to the PURCHASED state. Make sure that your integration expects an order ID only after a transaction has fully completed. You can still use the purchase token for your records.

For more information about handling pending purchases, see the Play Billing Library integration guide and the purchase lifecycle management guide.

Handle removed alternative billing APIs

Removed BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener, and AlternativeChoiceDetails. Developers should use BillingClient.Builder.enableUserChoiceBilling() with UserChoiceBillingListener and UserChoiceDetails in the listener callback instead.

This update is a renaming of the deprecated APIs with no behavior changes.

Optional Changes

PBL 7 includes two new optional APIs.

Support Pending Purchases for Prepaid Plans

See the Handle Subscriptions and Pending Transactions guide.

Virtual Installment Subscriptions

See the Installment Subscriptions Integration guide.

Upgrade from PBL 6 to PBL 7

The following sections describe how to upgrade from PBL 6 to PBL 7.

Update Google Play Billing Library

Update the Play Billing Library dependency version in your app's build.gradle file.

dependencies {
    def billingVersion = 7.0.0

    implementation "com.android.billingclient:billing:$billingVersion"
}

Next, update your API references as described in the following sections.

Handle subscription related API changes

The previously deprecated APIs setOldSkuPurchaseToken, setReplaceProrationMode, setReplaceSkusProrationMode have been removed.

Handle removed alternative billing APIs

Removed BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener and AlternativeChoiceDetails. Developers should use BillingClient.Builder.enableUserChoiceBilling() with UserChoiceBillingListener and UserChoiceDetails in the listener callback instead.

Optional Changes

PBL 7 includes two new optional APIs.

Support Pending Purchases for Prepaid Plans

See the Handle Subscriptions and Pending Transactions guide.

Virtual Installment Subscriptions

See the Installment Subscriptions Integration guide for information on how to integrate these changes into your app.