Terminal
Terminal/Skill
Step by step guide to migrating an Android app from Play Billing Library 7 to 8, covering renamed APIs, the dependency bump, and verification.
By RevenueCat
Works with
npx skills add revenuecat/play-billing-skills --skill pbl-v7-to-v8-migrationAnnounce to the user: "I will migrate this project from PBL 7 to PBL 8."
State that the migration is mechanical rather than architectural. The billing flow, backend integration, and product catalog stay the same. You are renaming classes, updating method signatures, and removing calls that PBL 8 deleted.
If the goal is to land on the current major (PBL 9), use pbl-v7-to-v9-migration instead. It runs this same v7 to v8 work first, then applies the small v8 to v9 delta. PBL 8 itself stops accepting new app and update submissions on August 31, 2027, so prefer going straight to v9 unless you have a reason to stop at 8.
Gather the facts before changing anything.
build.gradle, build.gradle.kts, or libs.versions.toml and find com.android.billingclient:billing. Record the current version string.7.x.x, treat the baseline as PBL 7. If the string is older (for example 5.x or 6.x) but the code still compiles against PBL 7 APIs, also treat the baseline as PBL 7 for this skill. You can migrate directly from 5 or 6 to 8 by following the same steps.compileSdk. Read build.gradle and note the value. You will bump it in Phase 3 if needed.enableAlternativeBilling, AlternativeBillingListener, and AlternativeChoiceDetails. If any hit, the alternative billing rename block in Phase 3 applies.Report back: "You are on PBL [current]. I found [N] deprecated call sites across [M] files. Planning a direct migration to PBL 8.1."
Build the checklist. Every item maps to a breaking change from appendix D.
| Area | PBL 7 (removed or changed) | PBL 8 replacement |
|---|---|---|
| Purchase history | queryPurchaseHistoryAsync() | queryPurchasesAsync() (no history replacement on client) |
| Product queries | querySkuDetailsAsync() | queryProductDetailsAsync() |
| Pending purchases | enablePendingPurchases() (no args) | enablePendingPurchases(PendingPurchasesParams) |
| Product details result | ProductDetailsResponseListener returning List<ProductDetails> | QueryProductDetailsResult return value |
| Alternative billing toggle | enableAlternativeBilling() | enableUserChoiceBilling() |
| Alternative billing listener | AlternativeBillingListener | UserChoiceBillingListener |
| Alternative choice details | AlternativeChoiceDetails | UserChoiceDetails |
| Alternative choice product | AlternativeChoiceDetails.Product | UserChoiceDetails.Product |
| Proration enum | ProrationMode | ReplacementMode |
| Proration setter | setReplaceProrationMode() | setSubscriptionReplacementMode() |
| Subscription update params | SubscriptionUpdateParams | SubscriptionProductReplacementParams (PBL 8.1) |
| Service reconnection | Manual retry loop | enableAutoServiceReconnection() |
ProrationMode (PBL 7) | ReplacementMode (PBL 8) |
|---|---|
IMMEDIATE_WITH_TIME_PRORATION | WITH_TIME_PRORATION |
IMMEDIATE_AND_CHARGE_PRORATED_PRICE | CHARGE_PRORATED_PRICE |
IMMEDIATE_AND_CHARGE_FULL_PRICE | CHARGE_FULL_PRICE |
IMMEDIATE_WITHOUT_PRORATION | WITHOUT_PRORATION |
DEFERRED | DEFERRED |
| (none) | KEEP_EXISTING (PBL 8.1+) |
Present the plan to the user as a checklist and confirm before editing files.
Work through the steps in order. Each step lifts a block from appendix D.
Update the version string to the latest stable PBL 8 release. Target 8.1 or later so you get SubscriptionProductReplacementParams and includeSuspendedSubscriptions in the same pass.
implementation("com.android.billingclient:billing-ktx:8.1.0")
Sync Gradle. Expect compile errors. They guide the rest of this phase.
BillingClient builderReplace the parameterless enablePendingPurchases() with the params object. Add enableAutoServiceReconnection() in the same builder chain.
val billingClient = BillingClient.newBuilder(context)
.setListener(purchasesUpdatedListener)
.enablePendingPurchases(
PendingPurchasesParams.newBuilder()
.enableOneTimeProducts()
.enablePrepaidPlans()
.build()
)
.enableAutoServiceReconnection()
.build()
You must call at least one of enableOneTimeProducts() or enablePrepaidPlans(). Call both if the app sells both.
queryPurchaseHistoryAsyncPBL 8 removed this method. The replacement is queryPurchasesAsync, which returns active purchases only.
val result = billingClient.queryPurchasesAsync(
QueryPurchasesParams.newBuilder()
.setProductType(ProductType.SUBS)
.build()
)
result.purchasesList.forEach { purchase -> handle(purchase) }
If the app needs historical purchase data for analytics, move that lookup to the backend through the Google Play Developer API (Purchases.subscriptionsv2 or Purchases.products).
querySkuDetailsAsyncSwitch to queryProductDetailsAsync with the product based params builder.
val params = QueryProductDetailsParams.newBuilder()
.setProductList(listOf(
QueryProductDetailsParams.Product.newBuilder()
.setProductId("premium_monthly")
.setProductType(ProductType.SUBS)
.build()
)).build()
Update downstream display code. SkuDetails.price is gone. ProductDetails exposes subscriptionOfferDetails, base plans, and pricing phases.
QueryProductDetailsResult return valuePBL 8 returns a result object instead of invoking a listener with a nullable list.
val result = billingClient.queryProductDetailsAsync(params)
if (result.billingResult.responseCode == BillingResponseCode.OK) {
result.productDetailsList.forEach { displayProduct(it) }
result.unfetchedProductList.forEach { logUnfetchedProduct(it) }
}
Read unfetchedProductList during the same pass. Each UnfetchedProduct carries a productId and reason, which you should log for diagnostics.
Apply the rename everywhere the grep from Phase 1 found a hit.
.enableUserChoiceBilling(
UserChoiceBillingListener { details ->
val products = details.products
val token = details.externalTransactionToken
handleUserChoiceBilling(products, token)
}
)
The callback payload shape is unchanged. Only the names move.
ProrationMode with ReplacementModeUse the constant map in Phase 2. Update the setter name from setReplaceProrationMode to setSubscriptionReplacementMode.
val updateParams = BillingFlowParams.SubscriptionUpdateParams.newBuilder()
.setOldPurchaseToken(oldToken)
.setSubscriptionReplacementMode(ReplacementMode.CHARGE_PRORATED_PRICE)
.build()
SubscriptionProductReplacementParams (PBL 8.1)When targeting 8.1 or later, move the replacement configuration off BillingFlowParams and onto ProductDetailsParams.
val replacementParams = BillingFlowParams
.SubscriptionProductReplacementParams.newBuilder()
.setOldPurchaseToken(oldToken)
.setReplacementMode(ReplacementMode.CHARGE_PRORATED_PRICE)
.build()
Attach replacementParams to the product params through setSubscriptionReplacementParams(replacementParams).
With enableAutoServiceReconnection() set in Step 2, remove manual startConnection() retries from onBillingServiceDisconnected(). Keep the callback for logging or a reconnecting UI hint if you want one.
Inside PurchasesUpdatedListener, read billingResult.getOnPurchasesUpdatedSubResponseCode() for a finer grained failure reason (for example insufficient funds).
includeSuspendedSubscriptions (PBL 8.1, optional)val params = QueryPurchasesParams.newBuilder()
.setProductType(ProductType.SUBS)
.includeSuspendedSubscriptions(true)
.build()
This surfaces account hold and grace period subscriptions on the client so you can prompt for a payment update without waiting on a backend signal.
PBL 8 ships different class names. Update any keep rules that referenced removed classes (SkuDetails, AlternativeBillingListener, and friends).
Prove the migration works before handing back.
./gradlew clean assembleDebug. Resolve any remaining references to removed APIs../gradlew test. Fix any tests that stub the old listener shapes or proration constants.ReplacementModestartConnection() call.result.unfetchedProductList with a reason.Report back a final summary: the old version, the new version, every rename applied, new features adopted, and the verification evidence.
Upstream deadline to track: PBL 7 support ends August 31, 2026. Aim to be in production on PBL 8 by June 2026 to leave room for two full billing cycles of monitoring.