Migrating to Google Play Billing 7: what changed

Google Play Billing Library 7 (released mid-2025) introduced significant changes to the subscription purchase flow, lifecycle management, and error handling. If you are still on Billing Library 5 or 6, the migration is mandatory — Google deprecates older versions on a rolling basis. Here is what breaks and how to fix it.

What is new in Billing Library 7

The headline changes in Billing 7 are:

• Unified purchase flow: BillingFlowParams has been restructured. The setSkuDetails method is deprecated; you now pass ProductDetails and SubscriptionOfferDetails objects directly.
• New lifecycle API: Subscriptions now have explicit states: active, in grace period, on hold, paused, and cancelled. The old autoRenewing boolean is replaced by a richer SubscriptionState enum.
• Win-back pricing: Billing 7 introduces native support for win-back offers — discounted pricing shown to lapsed subscribers. This is configured in Play Console and surfaced through the billing library.
• Pending purchases: The billing library now distinguishes between "pending" (payment processing) and "completed" purchases more explicitly. Your app must handle the pending state correctly.

What breaks when you migrate

1. Product querying changes

In Billing 5/6, you called querySkuDetailsAsync. In Billing 7, that method is removed. Use queryProductDetailsAsync with QueryProductDetailsParams instead. The response type is ProductDetails (not SkuDetails), and subscription offers are nested within ProductDetails.subscriptionOfferDetails.

// Billing 7 — correct approach
val params = QueryProductDetailsParams.newBuilder()
  .setProductList(listOf(
    QueryProductDetailsParams.Product.newBuilder()
      .setProductId("pro_monthly")
      .setProductType(BillingClient.ProductType.SUBS)
      .build()
  ))
  .build()
billingClient.queryProductDetailsAsync(params) { billingResult, productDetailsList ->
  // productDetailsList is List
}

2. Purchase state handling

The Purchase.getPurchaseState() int (0 = purchased, 1 = cancelled, 2 = pending) is replaced with richer APIs. You should now check Purchase.isAutoRenewing() for subscription status and use RTDN webhooks for lifecycle events rather than polling getPurchaseState().

Server-side: what stays the same

The good news: purchase token verification on the server side — calling the Android Publisher API — has not changed. If you already verify purchases server-side (through Tierux or the Publisher API directly), the migration only affects your client-side billing code. The purchase tokens, verification flow, and entitlement model remain identical.

The more of your billing logic lives server-side, the less painful Billing Library migrations become. Client-side billing code changes every library version; server-side verification stays stable.