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](https://developer.android.com/google/play/billing/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`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.ProrationMode)
to apply changes to a user's subscription purchases, such as upgrades
or downgrades. This API has been removed and replaced with
[`ReplacementMode`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.ReplacementMode).

### Handle subscription price changes

The previously deprecated `launchPriceConfirmationFlow` API has been removed.
For alternatives, see the [price changes
guide](https://developer.android.com/google/play/billing/price-changes).

### Handle subscription related API changes

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

- Update `setOldSkuPurchaseToken` to [`setOldPurchaseToken`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.Builder#setOldPurchaseToken).
- Update `setReplaceProrationMode` to [`setSubscriptionReplacementMode`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.Builder#setSubscriptionReplacementMode).
- Update `setReplaceSkusProrationMode` to [`setSubscriptionReplacementMode`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.Builder#setSubscriptionReplacementMode).

### 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](https://developer.android.com/google/play/billing/errors).

### 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`](https://developer.android.com/reference/com/android/billingclient/api/Purchase.PurchaseState#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](https://developer.android.com/google/play/billing/integrate) and the
[purchase lifecycle management guide](https://developer.android.com/google/play/billing/lifecycle).

### Handle removed alternative billing APIs

Removed [`BillingClient.Builder.enableAlternativeBilling`](https://developer.android.com/reference/com/android/billingclient/api/BillingClient.Builder#enableAlternativeBilling(com.android.billingclient.api.AlternativeBillingListener)),
[`AlternativeBillingListener`](https://developer.android.com/reference/com/android/billingclient/api/AlternativeBillingListener),
and [`AlternativeChoiceDetails`](https://developer.android.com/reference/com/android/billingclient/api/AlternativeChoiceDetails).
Developers should use [`BillingClient.Builder.enableUserChoiceBilling()`](https://developer.android.com/reference/com/android/billingclient/api/BillingClient.Builder#enableUserChoiceBilling(com.android.billingclient.api.UserChoiceBillingListener)) with [`UserChoiceBillingListener`](https://developer.android.com/reference/com/android/billingclient/api/UserChoiceBillingListener)
and [`UserChoiceDetails`](https://developer.android.com/reference/com/android/billingclient/api/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](https://developer.android.com/google/play/billing/subscriptions#pending) guide.

#### Virtual Installment Subscriptions

See the [Installment Subscriptions Integration](https://developer.android.com/google/play/billing/subscriptions#installments) 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.

- Update `setOldSkuPurchaseToken` to [`setOldPurchaseToken`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.Builder#setOldPurchaseToken).
- Update `setReplaceProrationMode` to [`setSubscriptionReplacementMode`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.Builder#setSubscriptionReplacementMode).
- Update `setReplaceSkusProrationMode` to [`setSubscriptionReplacementMode`](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.SubscriptionUpdateParams.Builder#setSubscriptionReplacementMode).

### Handle removed alternative billing APIs

Removed [`BillingClient.Builder.enableAlternativeBilling`](https://developer.android.com/reference/com/android/billingclient/api/BillingClient.Builder#enableAlternativeBilling(com.android.billingclient.api.AlternativeBillingListener)),
[`AlternativeBillingListener`](https://developer.android.com/reference/com/android/billingclient/api/AlternativeBillingListener)
and [`AlternativeChoiceDetails`](https://developer.android.com/reference/com/android/billingclient/api/AlternativeChoiceDetails).
Developers should use [`BillingClient.Builder.enableUserChoiceBilling()`](https://developer.android.com/reference/com/android/billingclient/api/BillingClient.Builder#enableUserChoiceBilling(com.android.billingclient.api.UserChoiceBillingListener)) with [`UserChoiceBillingListener`](https://developer.android.com/reference/com/android/billingclient/api/UserChoiceBillingListener)
and [`UserChoiceDetails`](https://developer.android.com/reference/com/android/billingclient/api/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](https://developer.android.com/google/play/billing/subscriptions#pending) guide.

#### Virtual Installment Subscriptions

See the [Installment Subscriptions Integration](https://developer.android.com/google/play/billing/subscriptions#installments) guide for
information on how to integrate these changes into your app.