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

For a full list of the changes in version 8.0.0, refer to the [release
notes](https://developer.android.com/google/play/billing/release-notes).

## Overview

PBL 8 contains improvements to existing APIs along with the removal of
previously deprecated APIs. This version of the library also includes new
APIs for one-time products.

## Backward-compatibility for PBL upgrade

To migrate to PBL 8, you need to update or remove some of your existing API
references from your app, as described in the [release notes](https://developer.android.com/google/play/billing/release-notes) and later
in this migration guide.

## Upgrade from PBL 6 or 7 to PBL 8

To upgrade from PBL 6 or 7 to PBL 8, do the following steps:

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

       dependencies {
         def billingVersion = 8.0.0
         implementation "com.android.billingclient:billing:$billingVersion"
       }

2. (Applicable only for upgrade from PBL 6 to PBL 8). Handle subscription
   related API changes in your app.

   The following table lists the subscription related APIs that are removed in
   PBL 8 and the corresponding alternate API that you must use in your app.

   | Previously deprecated API removed in PBL 8 |                                                                                   Alternate API to use                                                                                    |
   |--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
   | setOldSkuPurchaseToken                     | [setOldPurchaseToken](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.Builder#setOldPurchaseToken)                       |
   | setReplaceProrationMode                    | [setSubscriptionReplacementMode](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.Builder#setSubscriptionReplacementMode) |
   | setReplaceSkusProrationMode                | [setSubscriptionReplacementMode](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.Builder#setSubscriptionReplacementMode) |

3. Update the implementation of the [`queryProductDetailsAsync`](https://developer.android.com/reference/com/android/billingclient/api/BillingClient#queryProductDetailsAsync) method.

   There is a change in the signature of the
   [`ProductDetailsResponseListener.onProductDetailsResponse`](https://developer.android.com/reference/com/android/billingclient/api/ProductDetailsResponseListener#onProductDetailsResponse(com.android.billingclient.api.BillingResult,java.util.List%3Ccom.android.billingclient.api.ProductDetails%3E)) method, which
   requires changes in your app for the [`queryProductDetailsAsync`](https://developer.android.com/reference/com/android/billingclient/api/BillingClient#queryProductDetailsAsync)
   implementation. For more information, see
   [Show products available to buy](https://developer.android.com/google/play/billing/integrate#show-products).
4. Handle the removed APIs.

   ### Upgrade from


   PBL 8 no longer supports the APIs listed in the following table.
   If your implementation uses any of these removed APIs,
   refer to the table for their corresponding alternate APIs.

   |               Previously deprecated API removed in PBL 8                |                                                                                                                                                                                          Alternate API to use                                                                                                                                                                                          |
   |-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
   | queryPurchaseHistoryAsync APIs                                          | See [Query Purchase History](https://developer.android.com/google/play/billing/query-purchase-history)                                                                                                                                                                                                                                                                                                 |
   | querySkuDetailsAsync                                                    | [queryProductDetailsAsync](https://developer.android.com/reference/com/android/billingclient/api/BillingClient#queryProductDetailsAsync(com.android.billingclient.api.QueryProductDetailsParams,com.android.billingclient.api.ProductDetailsResponseListener))                                                                                                                                         |
   | enablePendingPurchases() (API without parameters)                       | [enablePendingPurchases(PendingPurchaseParams params)](https://developer.android.com/reference/com/android/billingclient/api/BillingClient#enablePendingPurchases(com.android.billingclient.api.PendingPurchaseParams)) Note that the deprecated enablePendingPurchases() is functionally equivalent to `enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())`. |
   | queryPurchasesAsync(String skuType, PurchasesResponseListener listener) | [queryPurchasesAsync](https://developer.android.com/reference/com/android/billingclient/api/BillingClient#queryPurchasesAsync(com.android.billingclient.api.QueryPurchasesParams,com.android.billingclient.api.PurchasesResponseListener))                                                                                                                                                             |
   | BillingClient.Builder.enableAlternativeBilling                          | [BillingClient.Builder.enableUserChoiceBilling](https://developer.android.com/reference/com/android/billingclient/api/BillingClient.Builder#enableUserChoiceBilling(com.android.billingclient.api.UserChoiceBillingListener))                                                                                                                                                                          |
   | AlternativeBillingListener                                              | [UserChoiceBillingListener](https://developer.android.com/reference/com/android/billingclient/api/UserChoiceBillingListener)                                                                                                                                                                                                                                                                           |
   | AlternativeChoiceDetails                                                | [UserChoiceDetails](https://developer.android.com/reference/com/android/billingclient/api/UserChoiceDetails)                                                                                                                                                                                                                                                                                           |

   <br />

   ### Upgrade from


   The following table lists the APIs that are removed in PBL 8, and the
   corresponding alternate APIs that you must use in your app.

   |               Previously deprecated API removed in PBL 8                |                                                                                                                                                                                          Alternate API to use                                                                                                                                                                                          |
   |-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
   | queryPurchaseHistoryAsync APIs                                          | See [Query Purchase History](https://developer.android.com/google/play/billing/query-purchase-history)                                                                                                                                                                                                                                                                                                 |
   | querySkuDetailsAsync                                                    | [queryProductDetailsAsync](https://developer.android.com/reference/com/android/billingclient/api/BillingClient#queryProductDetailsAsync(com.android.billingclient.api.QueryProductDetailsParams,com.android.billingclient.api.ProductDetailsResponseListener))                                                                                                                                         |
   | enablePendingPurchases() (API without parameters)                       | [enablePendingPurchases(PendingPurchaseParams params)](https://developer.android.com/reference/com/android/billingclient/api/BillingClient#enablePendingPurchases(com.android.billingclient.api.PendingPurchaseParams)) Note that the deprecated enablePendingPurchases() is functionally equivalent to `enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())`. |
   | queryPurchasesAsync(String skuType, PurchasesResponseListener listener) | [queryPurchasesAsync](https://developer.android.com/reference/com/android/billingclient/api/BillingClient#queryPurchasesAsync(com.android.billingclient.api.QueryPurchasesParams,com.android.billingclient.api.PurchasesResponseListener))                                                                                                                                                             |

   <br />

5. (Recommended) Enable automatic service reconnection.

   The Play Billing Library can attempt to automatically re-establish the
   service connection if an API call is made while the service is
   disconnected. For more information,
   see [Enable automatic service reconnection](https://developer.android.com/google/play/billing/integrate#automatic-service-reconnection).
6. Optional changes.

   - Support pending purchases for prepaid plans. For more information, see
     [Handle Subscriptions and Pending Transactions](https://developer.android.com/google/play/billing/subscriptions#pending).

   - Virtual installment subscriptions. For more information, see
     [Installment Subscriptions Integration](https://developer.android.com/google/play/billing/subscriptions#installments).