Play Billing Library 8 Migration: From v7 to v8, With a Head Start on v9
The deadline is a publishing gate, not a runtime switch
Google supports each major Play Billing Library version for two years after release, then stops accepting new builds compiled against it. The deprecation FAQ publishes the exact dates, reproduced in the Play Billing deprecation schedule table below.
Read the rule precisely: the cutoff blocks new apps and updates from using older library versions. Apps already published on a deprecated version keep working. So a v7 binary in the store continues to transact after August 31, 2026 — what ends is your ability to ship anything new, including security and bug fixes. If your app is still maintained at all, you need v8 before that date. The November 1, 2026 extension deadline is for filing a formal request through the Play Console to keep shipping v7 builds for a short additional window; it is not granted automatically.
The Play Console surfaces this through a warning and an inbox message on the Policy status page. That signal depends on a manifest entry named com.google.android.play.billingclient.version. The library adds it automatically, but manifest merging in multi-module projects can drop it. Check your final merged manifest before you conclude that no warning means no problem.
What v8 removed, and what replaces it
Several APIs deprecated in one or two prior versions are gone in v8. Code that still references them will not compile until it is replaced. The Play Billing v8 removed APIs and replacements table lists each one with its replacement.
One signature change sits outside the table and catches implementers: ProductDetailsResponseListener.onProductDetailsResponse() now hands back a QueryProductDetailsResult. That object keeps the products that loaded and the products that did not in separate collections, and every failed entry carries its own status code. Any class implementing that listener must be updated even if its logic is otherwise unchanged.
Two naming notes come with the removals. "In-app items" are now called "one-time products" in documentation and the API surface; class names did not change. The rename carries behavior: one-time products in v8 can carry multiple purchase options and offers, as subscriptions could in v7.
Step 1: Bump the dependency and decide on minSdk
Start with the Gradle coordinate. v8.0.0 opened the v8 line, but most teams should target the latest patch in the series rather than pinning to 8.0.0. The exact dependency block is provided in the Gradle dependency snippet.
minSdkVersion rose to 23 starting at v8.1.0. If you still support API 21 or 22 you have two options: pin to 8.0.0, which keeps the v7 minSdk of 21, or raise your own minSdk to 23 and take the latest v8 patch. For almost every team the second is the right call — API 23 dates from 2015 and the device tail below it has been negligible for years. v8.1 is also built against Kotlin 2.2.0, which can matter for projects on older Kotlin versions if you consume the billing-ktx artifact; for a project already on a recent Kotlin Compose stack the jump is small.
Step 2: Replace the no-argument enablePendingPurchases
The zero-argument enablePendingPurchases() was deprecated in v7 and removed in v8. It implicitly enabled pending purchase support for in-app items. v8 requires a builder that makes the product categories explicit. The v7 call and the v8 equivalent are provided in the pending purchases snippets.
Note that .enableOneTimeProducts() is not implicit. Google described the deprecated zero-argument version as equivalent to a builder with that flag set, so omitting it silently drops pending purchase support for one-time products. That regression is invisible in unit tests and in most credit-card markets; it shows up as broken purchases where users pay with cash at convenience stores or by bank transfer — primarily Japan, Germany, Brazil, Mexico, and Indonesia. Include .enableOneTimeProducts() even if you believe you do not need it.
If you sell prepaid subscription top-ups, also add .enablePrepaidPlans() to the builder. It was introduced in v7 for prepaid plan pending transactions and carries into v8 unchanged.
Step 3: Adapt queryProductDetailsAsync to the new callback
queryProductDetailsAsync itself survives; its callback did not. In v7 the listener handed you a BillingResult plus a List<ProductDetails>. In v8 the same call delivers a BillingResult plus a QueryProductDetailsResult, which keeps loaded products and failed products in separate collections. A product that could not be fetched now lands in the unfetched list with its own status code rather than disappearing without a trace. Both callback shapes are provided in the product details snippets.
Why this matters: before v8, querying five products where one was misconfigured in the Play Console could return success with that product silently absent. Your paywall rendered four products and you had no signal the fifth was attempted. The new shape makes partial failure explicit, and each unfetched entry's status code distinguishes unavailability in the user's country, an unpublished product, and a transient error.
This is also the moment to rebuild any coroutine or flow wrapper around queryProductDetailsAsync. A suspending wrapper can no longer return List<ProductDetails>; it needs a sealed class or pair that carries the unfetched information forward. A typealias for the listener type needs updating as well, because the lambda signature differs.
Step 4: Swap the deprecated queryPurchasesAsync overload
The overload of queryPurchasesAsync that accepted a raw SKU type string is removed in v8. Its replacement uses a QueryPurchasesParams builder wrapping the same product type with the new typed enum. Before and after forms are provided in the query purchases snippets.
Called correctly, the new overload behaves the same as the old one. The SkuType constants are gone; ProductType.SUBS and ProductType.INAPP take their place. If a shared method takes a string for the SKU type, either refactor it to accept a String matching the new enum values or convert it to use BillingClient.ProductType directly.
Step 5: Replace queryPurchaseHistoryAsync with server-side history
queryPurchaseHistoryAsync was deprecated in v7 and fully removed in v8, with no equivalent client API. It is the only v8 removal without a direct one-to-one replacement, and it tends to surprise teams the most.
The reasoning is straightforward: purchase history is not authoritative on the client. Any history a device builds can be incomplete — the device may have been offline during a refund or revocation. The Play Developer API on your server holds the authoritative record, so analytics, audit, and reconciliation flows that depend on past purchases should query it server-side.
If you used queryPurchaseHistoryAsync, you now have two paths. First, call the Play Developer API endpoint purchases.subscriptionsv2.get from your backend whenever you need a subscription's full history, including its linkedPurchaseToken chain. Second, consume Real Time Developer Notifications and persist events as they arrive, building your own purchase history table. Most teams already do the latter for analytics and revenue reporting, in which case the removal is a no-op.
If you used it for entitlement restoration on a fresh install or reinstall, switch to queryPurchasesAsync with the new params builder. That returns active purchases tied to the current Google account, which is what restoration actually needs — a smaller set than full history, but the correct set for granting entitlements. Note that v8 also stops returning consumed one-time products and expired subscriptions from queryPurchasesAsync, so configure one-time products as non-consumable in the Play Console if they must survive a reinstall.
Step 6: Move from alternative billing to user choice billing
The enableAlternativeBilling builder method was already deprecated in v7, and v8 drops it altogether. In its place, enableUserChoiceBilling accepts a UserChoiceBillingListener rather than an AlternativeBillingListener and delivers a UserChoiceDetails payload rather than AlternativeChoiceDetails. The builder form is provided in the user choice billing snippet.
The functional contract is unchanged: if a user chooses your billing system instead of Google Play's during checkout, the listener fires with the purchase details so your backend can finish the transaction outside Google Play's payment flow. Only the type names changed. If you carry per-region build flavors that enable user choice billing in some regions and not others, the flavor logic stays as is; only the type references move.
One-time products and the multi-offer surface
v8 renamed in-app items to one-time products and gave them the multi-offer capability subscriptions have had since v5. A single one-time product can now carry multiple purchase options, each with its own price, regional availability, and attached offers. This change motivates much of v8's surface, and it is why the unfetched product list now exists: with multiple offers per product, partial failure modes multiplied and a flat list could no longer represent what happened. The type names are untouched — ProductDetails remains ProductDetails. The shift is in the oneTimePurchaseOfferDetails accessor, which from v8.1.0 can return several offers plus pre-order details. A paywall that shows a single price for an in-app item is still operating on the v7 model. Under v8 you can present a discounted or region-specific offer on one product instead of duplicating the SKU. Nothing changes until you opt in: existing one-time products keep returning one offer until extra options are configured in the Play Console.
Two v8 additions worth adopting at migration time
Neither of the following is strictly required, but both remove code you would otherwise maintain yourself. First, enableAutoServiceReconnection(). The Play Billing service can disconnect for several reasons: the user installs a Google Play update, the device wakes from a long sleep, the system reclaims the bound service. Before v8 you implemented onBillingServiceDisconnected() and called startConnection() again with backoff. v8 ships an opt-in builder method that handles retry with backoff internally; the builder form is provided in the auto reconnection snippet. With it enabled, your onBillingServiceDisconnected() override can be a no-op. It is opt-in rather than default — leave it disabled if you want to manage the connection lifecycle yourself. Second, BillingResult.subResponseCode. Before v8, purchase failures were grouped under BILLING_UNAVAILABLE or ERROR. v8 adds a sub response code that distinguishes specific cases: - PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS: the user's payment method lacks sufficient funds. - USER_INELIGIBLE: the user is not eligible for the offer they tried to redeem, typically because they already used a one-time intro offer. - NO_APPLICABLE_SUB_RESPONSE_CODE: the failure does not map to a more specific sub code. USER_INELIGIBLE is the code most teams will want to act on: it lets you redirect the user toward a fallback offer rather than stranding them on a failed purchase screen. The sub code is carried in the BillingResult passed to PurchasesUpdatedListener.onPurchasesUpdated; the handling pattern is provided in the sub response code snippet.
What v8.1, v8.2, and v8.3 add
v8 has moved quickly since general availability. Three minor releases between November and December 2025 added capabilities that are easy to miss if you only read the v8.0 migration guide. v8.1.0, released November 6, 2025, introduced suspended subscription handling. A subscription enters the suspended state when Google detects abuse or a payment dispute and pauses entitlement delivery without canceling the subscription. Before v8.1, suspended subscriptions were invisible to client-side queries. v8.1 adds an isSuspended flag on Purchase and a parameter to queryPurchasesAsync to include suspended purchases in the result. The pattern is to filter purchases by isSuspended before granting entitlement and route suspended ones into a separate UI branch explaining the hold; the query form is provided in the suspended subscription snippet. v8.1 also reworks subscription replacement. SubscriptionUpdateParams.setSubscriptionReplacementMode() is now deprecated; SubscriptionProductReplacementParams, set on the per-product builder, takes over. The new shape supports a KEEP_EXISTING replacement mode, which lets you upsell a second subscription on the same account without canceling the existing one — useful for bundled offerings. v8.2.0 and v8.2.1, released in December 2025, generalize what was the External Offers Program into a broader Billing Program surface. The old methods (enableExternalOffer, isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync, showExternalOfferInformationDialog) are deprecated and replaced by enableBillingProgram(int), isBillingProgramAvailableAsync, createBillingProgramReportingDetailsAsync, and launchExternalLink. v8.3.0, shipped December 23, 2025, adds the developer-provided billing flow on top, with BillingProgram.EXTERNAL_PAYMENTS, EnableBillingProgramParams, and DeveloperBillingOptionParams. This consolidation responds to regulatory pressure from the Epic Games ruling and similar requirements in other jurisdictions, where Google must support developer-provided billing and out-of-app payment links. If your app still relies on the External Offers Program, treat the deprecation as a prompt to begin moving. Those methods continue to function in v8.2 and v8.3 but are likely to disappear in v9. Shifting to the Billing Program surface now costs you once and spares you a forced migration down the line.
Preparing for v9 before its API exists
Release notes currently top out at v8.3.0. The deprecation FAQ lists no v9 row, and there is no public alpha, beta, or release candidate. Preparation therefore comes from cadence and direction of change. Google has shipped a new major Play Billing Library version roughly once a year: v7 in May 2024, v8 reaching GA on June 30, 2025. On that pattern, v9 would be expected around mid-2027, aligning with the v8 sunset deadline of August 31, 2027. The direction is also readable from the rapid v8.1–v8.3 releases: Google is consolidating the external billing surface (External Offers Program, user choice billing, developer-provided billing) into a unified Billing Programs API. v9 is likely to remove the deprecated External Offers methods, formalize the Billing Programs surface, and possibly extend it to further regulatory regimes. Three things to do today: - Adopt opt-ins early. Turn on every opt-in API v8 offers, including enableAutoServiceReconnection() and the new SubscriptionProductReplacementParams. What is opt-in in one major version usually becomes the default in the next. - Leave External Offers behind. The Billing Programs surface in v8.2 and v8.3 is where things are heading, and it gives you a non-breaking window to migrate before v9 makes it mandatory. - Keep history on the server. queryPurchaseHistoryAsync was removed in v8 deliberately, and v9 will not bring it back. Assemble your purchase audit trail server-side from RTDN events and the Play Developer API. Doing all three during the v8 migration makes the v9 move incremental rather than disruptive.
Migration checklist: separate compile failures from silent regressions
Not every v8 problem announces itself. Sort your work by how it fails:
Compile-time failures (safe — the compiler finds them):
- querySkuDetailsAsync, the no-argument enablePendingPurchases, the string-overload queryPurchasesAsync, enableAlternativeBilling, and the AlternativeBillingListener / AlternativeChoiceDetails types.
- Any ProductDetailsResponseListener implementation, because the callback parameter type changed.
Silent runtime regressions (the compiler will not help):
- Missing .enableOneTimeProducts() in PendingPurchasesParams: pending purchases break in cash and bank-transfer markets while tests stay green.
- A paywall still rendering one price per one-time product: you are leaving configured offers invisible.
- Consumed one-time products expected to survive reinstall: v8 no longer returns them from queryPurchasesAsync.
- Entitlement restoration still built on purchase history: history is gone from the client entirely.
Verification gates before release:
- Confirm com.google.android.play.billingclient.version exists in the final merged manifest.
- Exercise a pending purchase in at least one cash-payment market.
- Exercise a deliberately misconfigured product and confirm it appears in the unfetched list with a status code.
- Confirm suspended subscriptions route to a distinct UI branch rather than granting entitlement.
If a billing SDK sits between your app and Play Billing
Teams that use a billing SDK rather than calling Play Billing directly can often absorb this migration at the SDK layer. Where a vendor ships a version with Play Billing Library 8 already integrated, the app-side work can shrink to: bumping the SDK major version, meeting its Kotlin minimum, replacing any copy() or destructuring on public types that lost their data class modifier (equals() and hashCode() are preserved), and confirming one-time products are configured as non-consumables in the vendor dashboard, since v8 cannot query consumed one-time products. The v8-specific changes — the PendingPurchasesParams builder, the queryProductDetailsAsync callback shape, the queryPurchasesAsync overload swap, the user choice billing rename, and unfetched product handling — are then handled inside the SDK. Whether a given SDK actually bundles Play Billing 8 and limits app-side changes to those steps is a vendor-specific claim to verify against that SDK's own release notes and migration documentation before planning a release. Likewise, any expectation that a future SDK release will track Play Billing v9 on the same bump-and-test pattern is a forward-looking vendor commitment, not a guarantee; confirm it with the SDK provider rather than assuming it.
| Library version | Last date for new apps and updates | Extension request deadline |
|---|---|---|
| 5.x | 2024-08-31 | 2024-11-01 |
| 6.x | 2025-08-31 | 2025-11-01 |
| 7.x | 2026-08-31 | 2026-11-01 |
| 8.x | 2027-08-31 | 2027-11-01 |
Dates as published in Google's deprecation FAQ at the time this guide was written; confirm current dates before planning a release.
| Removed API | Replacement |
|---|---|
| querySkuDetailsAsync() | queryProductDetailsAsync(QueryProductDetailsParams, ProductDetailsResponseListener) |
| queryPurchaseHistoryAsync() (all overloads) | No direct client API. Track history server side. |
| enablePendingPurchases() (no arg) | enablePendingPurchases(PendingPurchasesParams) |
| queryPurchasesAsync(String skuType, PurchasesResponseListener) | queryPurchasesAsync(QueryPurchasesParams, PurchasesResponseListener) |
| BillingClient.Builder.enableAlternativeBilling() | enableUserChoiceBilling(UserChoiceBillingListener) |
| AlternativeBillingListener | UserChoiceBillingListener |
| AlternativeChoiceDetails | UserChoiceDetails |
Exact API names and replacements as documented for v8; verify against current release notes for later patches.
Frequently asked questions
Does the August 31, 2026 deadline break apps already live on v7?
No. The cutoff blocks new apps and updates compiled against v7 from being accepted. Existing published v7 binaries keep transacting. What you lose is the ability to ship any new release, including bug and security fixes, so a maintained app needs v8 before the gate closes.
How do I restore entitlements now that queryPurchaseHistoryAsync is gone?
Use queryPurchasesAsync with the new QueryPurchasesParams builder. It returns active purchases tied to the current Google account, which is the correct set for granting entitlements. Full purchase history is a server-side concern: use the Play Developer API endpoint purchases.subscriptionsv2.get or persist Real Time Developer Notifications.
Why did pending purchases stop working after upgrading to v8?
The zero-argument enablePendingPurchases() implicitly enabled pending support for in-app items. Its replacement requires an explicit builder, and if you omit .enableOneTimeProducts() you silently lose pending purchase support for one-time products. The symptom appears mainly in cash and bank-transfer markets such as Japan, Germany, Brazil, Mexico, and Indonesia, and unit tests will not catch it.
Should I pin to 8.0.0 or raise minSdk to 23?
Pinning to 8.0.0 keeps the v7 minSdk of 21. Raising your own minSdk to 23 lets you take the latest v8 patch, which is the right choice for almost every team given how small the below-23 device population has been for years. Note that v8.1 is built against Kotlin 2.2.0, which can matter if you consume billing-ktx on an older Kotlin version.
What does the unfetched product list actually tell me?
Each entry carries a status code that distinguishes cases such as the product being unavailable in the user's country, not yet published, or hit by a transient error. Before v8 a misconfigured product could simply vanish from a successful response; now the partial failure is visible and you can log or surface it.