Google Play Billing Library 7: what changed and how to migrate
Play Billing Library 7 arrived with two customer-facing additions — installment subscriptions and pending purchases for pre-paid plans — plus a set of API removals and renames that affect existing billing code. This guide walks through the feature changes, the support deadlines for older library versions, and a practical migration sequence from dependency bump to testing. Deadlines and country availability below reflect the situation as documented around the library's May 2024 release; confirm current dates and availability in Google's own documentation and Play Console before you plan a release.
What Play Billing Library 7 changes at a glance
Each major version has had a different character. Version 5 reworked subscription mechanics substantially. Version 6 was a narrower release, largely touching the technical handling of subscription statuses. Version 7 combines moderate API and endpoint adjustments with functionality that users can actually see in the purchase flow.
The changes worth planning around are installment subscriptions, pending purchases extended to pre-paid subscriptions, the retirement of the purchase-history query API, and a batch of removed or renamed methods. Everything else is best tracked in Google's release notes rather than in a summary.
Installment subscriptions: what they do and where they work
Installment subscriptions let a user pay for a subscription in smaller amounts instead of one lump sum, which lowers the upfront commitment. Two qualifications matter before you build a business case around it.
First, payouts are unaffected: for an annual plan billed in monthly installments, the developer still receives payouts monthly. Second, missed installments are not collected — neither Google nor the developer pursues an unpaid installment. That makes the feature's practical advantage over an ordinary monthly subscription narrower than it first appears.
Availability is limited. At release the feature was offered only in Brazil, France, Italy, and Spain, with Google directing developers to Play Console for current availability. Enabling it means implementing ProductDetails.InstallmentPlanDetails following Google's installment guide.
Pending purchases now cover pre-paid subscriptions
Pending transactions are purchases that need one or more extra steps between the user starting the flow and the payment method being processed — paying cash at a physical store is the classic example. Before version 7 these applied only to non-recurring payments; version 7 extends them to pre-paid subscriptions, refines how pending transaction statuses are handled across the board, and adds APIs for the pre-paid case.
In code, pending transactions for non-recurring payments are enabled by calling enablePendingPurchases() while initializing the billing client. Pre-paid plan support is switched on separately with PendingPurchasesParams.Builder.enablePrepaidPlans().
Purchase history moves off the client API
BillingClient.queryPurchaseHistoryAsync() is deprecated starting with version 7. If you call it today, you have about 1.5 years — until Play Billing Library 6 itself is deprecated — to stop relying on it. The documentation and I/O sessions do not give a clear reason for the removal, but acceptable alternatives are suggested for most use cases.
The exception is consumed purchases. If you currently use queryPurchaseHistoryAsync() to track what users have consumed, plan to record that on your own servers instead.
Support deadlines for Play Billing Library 5 and 6
With version 7 released, the clock started on the two older versions still supported at the time. The dates below are the deadlines as published around the release; check Google's deprecation FAQ for any extension or revision before scheduling work.
Play Billing Library 5, including any minor versions, was deprecated as of August 31, 2024: all new apps and updates to existing apps had to use version 6 or newer by that date. Developers needing more time could request an extension from Google until November 1, 2024.
Play Billing Library 6, including any minor versions, can be used to release new apps until August 1, 2025 at the latest, and to release updates to existing apps until November 1, 2025.
The practical distinction is between releasing a new app and shipping an update to an existing one. Version 5 was cut off for both on the same date, with a short extension window available on request. Version 6 keeps a gap between the new-app cutoff and the update cutoff.
Missing a deadline does not necessarily break an app already installed on users' devices — the consequence lands when you next need to publish. Adoption data captured on May 14, 2024 showed that a meaningful share of apps were still on older versions at that point.
Migration step 1: raise the dependency
Start by pointing your project at version 7 of the billing client. The dependency block below is the exact snippet to adapt; the version variable is what you bump.
Migration step 2: replace removed and renamed APIs
This is the step that usually produces compile errors, and it is worth working through methodically rather than fixing errors one at a time as the build reports them.
Upgrades and downgrades: if you came from version 5 you may still be using ProrationMode to apply subscription upgrades and downgrades. From version 6 onward, ReplacementMode is the type to use.
Removed subscription methods, with their replacements:
- setOldSkuPurchaseToken becomes setOldPurchaseToken
- setReplaceProrationMode becomes setSubscriptionReplacementMode
- setReplaceSkusProrationMode becomes setSubscriptionReplacementMode
Order IDs for pending purchases: no order ID is created while a purchase is pending. If you handle pending transactions for consumables, adjust your integration so an order ID is only expected once the transaction has fully completed.
Alternative billing renames: BillingClient.Builder.enableAlternativeBilling, AlternativeBillingListener, and AlternativeChoiceDetails are no longer usable. Use BillingClient.Builder.enableUserChoiceBilling() with UserChoiceBillingListener and UserChoiceDetails instead. Behavior is unchanged — this is a naming change only.
Migration step 3 (optional): update error handling
If you have custom logic that branches on billing errors, note that BillingResult now returns a NETWORK_ERROR code for connectivity problems, and SERVICE_TIMEOUT and SERVICE_UNAVAILABLE were updated as well. Review any switch or mapping you maintain over result codes so the new code is handled rather than falling into a default branch.
Migration step 4 (optional): adopt the new subscription APIs
Only take this step if you intend to use the new capabilities. Pending purchases for pre-paid plans and virtual installment subscriptions each have their own integration guide from Google; the migration itself does not require either.
Migration step 5: test before rollout
Testing is the one step that is not optional. Confirm the billing flow completes, subscriptions are managed correctly, and edge cases behave — especially where you adopted a new API.
Installments: no specific test cases were published at the time of writing, so treat installment flows as needing your own scenario coverage.
Pending purchases: use Google Play's license testers with a slow test card, which approves or declines after a few minutes. That delay is what lets you observe the pending state rather than only the final result.
A pre-migration checklist
Use this to sequence the work and to catch the changes that are easy to miss.
- Confirm which library version your app currently ships and which deadline applies to your next planned release.
- Bump the billing client dependency to version 7 and resolve compile errors from removed methods.
- Search the codebase for ProrationMode, setOldSkuPurchaseToken, setReplaceProrationMode, and setReplaceSkusProrationMode and replace each occurrence.
- Search for enableAlternativeBilling, AlternativeBillingListener, and AlternativeChoiceDetails and switch to the user-choice equivalents.
- Audit any code that reads an order ID from a purchase object and confirm it tolerates a pending purchase without one.
- Decide whether consumed-purchase tracking currently depends on queryPurchaseHistoryAsync() and, if so, move that record to your backend.
- Review error-code handling for NETWORK_ERROR, SERVICE_TIMEOUT, and SERVICE_UNAVAILABLE.
- Decide explicitly whether to adopt installments or pre-paid pending purchases; if not, skip that integration work.
- Run license-tester scenarios including a slow test card before releasing.
Where to read further
Google publishes the version 7.0.0 release notes, a dedicated migration guide, documentation on pending subscription transactions, and the installment subscription integration guide. The I/O 2024 session on scaling a business with Google Play covers the commercial framing. Links to each are listed with this article.
| Previous API or type | Use instead | Notes |
|---|---|---|
| ProrationMode | ReplacementMode | Applies from version 6 onward for subscription upgrades and downgrades |
| setOldSkuPurchaseToken | setOldPurchaseToken | Removed method |
| setReplaceProrationMode | setSubscriptionReplacementMode | Removed method |
| setReplaceSkusProrationMode | setSubscriptionReplacementMode | Removed method |
| BillingClient.Builder.enableAlternativeBilling | BillingClient.Builder.enableUserChoiceBilling() | No behavior change |
| AlternativeBillingListener | UserChoiceBillingListener | No behavior change |
| AlternativeChoiceDetails | UserChoiceDetails | No behavior change |
| BillingClient.queryPurchaseHistoryAsync() | Deprecated; use suggested alternatives or your own server | Consumed purchases must be tracked server-side |
Reflects the API surface documented at the version 7 release in May 2024. Verify against current release notes before relying on any entry.
| Library version | New apps | Updates to existing apps | Extension |
|---|---|---|---|
| Play Billing Library 5 (and minor versions) | Must use version 6 or newer by August 31, 2024 | Must use version 6 or newer by August 31, 2024 | Extension available from Google until November 1, 2024 |
| Play Billing Library 6 (and minor versions) | Until August 1, 2025 | Until November 1, 2025 | Not stated |
Deadlines as published around the May 2024 release. Confirm current dates with Google's deprecation FAQ.
| Feature | Published test support | Suggested approach |
|---|---|---|
| Virtual installment subscriptions | No specific test cases published at the time of writing | Build your own scenario coverage; watch for updates |
| Pending purchases for pre-paid plans | License testers with a slow test card that approves or declines after a few minutes | Exercise the pending state, not just the final result |
Describes test tooling available at the time of writing; Google may publish additional cases later.
Frequently asked questions
Do I have to migrate to Play Billing Library 7 right away?
Not necessarily. Version 7 is the newest release, but version 6 remained usable for new apps until August 1, 2025 and for updates to existing apps until November 1, 2025. Version 5 was cut off for both on August 31, 2024, with an extension available until November 1, 2024. Check the current deprecation FAQ before scheduling.
Does an installment subscription change when I get paid?
No. For an annual plan paid in monthly installments, the developer still receives payouts monthly. The installment structure changes what the user pays and when, not the payout cadence.
What happens if a user misses an installment payment?
Neither Google nor the developer attempts to collect the missed payment. That is one reason the feature's advantage over a standard monthly subscription is limited.
Why is there no order ID on a pending purchase?
Version 7 no longer creates an order ID while a purchase is pending. If your integration reads an order ID from a purchase object, it should only expect one after the transaction has fully completed.
How do I test a pending purchase?
Add license testers in Play Console and use the slow test card, which approves or declines after a few minutes. That window lets you observe the pending state before the final result arrives.
Can I keep using queryPurchaseHistoryAsync()?
It is deprecated from version 7 onward. You have about 1.5 years — until version 6 is deprecated — to move off it. For consumed purchases specifically, plan to track consumption on your own servers.