Terminal
Terminal/Skill
Guide to the Google Play purchase flow on Android, from building billing params and launching the purchase to handling results and posting to a backend.
By RevenueCat
Works with
npx skills add revenuecat/play-billing-skills --skill purchase-flowImplements the full client side purchase sequence: build BillingFlowParams, launch launchBillingFlow(), receive callbacks in PurchasesUpdatedListener, handle every response code, then verify, acknowledge, and grant access.
Use this skill when you need to:
PurchasesUpdatedListener and handle every BillingResponseCode.Out of scope: connecting BillingClient, querying ProductDetails, subscription upgrades or downgrades, and retry or error taxonomy beyond the launch results listed below.
Confirm the preconditions before you build params.
| Check | How | Why |
|---|---|---|
BillingClient connected | billingClient.isReady == true | Calls fail without a live connection. |
ProductDetails cached | Held from a prior queryProductDetailsAsync | Required input to ProductDetailsParams. |
| Pending purchases enabled | BillingClient.Builder.enablePendingPurchases(...) was called | Users with delayed payment cannot buy otherwise. |
| Existing ownership known | Ran queryPurchasesAsync() recently | Prevents ITEM_ALREADY_OWNED surprises. |
| Offer token resolved (subs only) | Selected from subscriptionOfferDetails | Missing token returns DEVELOPER_ERROR. |
Record the product type (INAPP vs SUBS), the selected basePlanId, and the chosen offerToken before moving on.
Decide the following before you call newBuilder().
setIsOfferPersonalized(true) only if the price was chosen by automated decision making for this user. EU regulation requires a disclosure, which Google Play renders for you.false. Do not set true for uniform promotional pricing.Group offers by base plan, then pick the best eligible offer. Google already filters offers the user cannot redeem.
val offersByPlan = productDetails
.subscriptionOfferDetails
?.groupBy { it.basePlanId }
?: emptyMap()
val chosenOffer = offersByPlan[selectedBasePlanId]
?.firstOrNull() ?: return
Whatever the user tapped in your UI must map to the exact offerToken you pass. Show the first pricingPhases entry (free trial, intro price) in the UI and the recurring phase after it.
Decide whether acknowledge and grant happen server side (primary) or client side (fallback). Server side keeps verify, grant, and acknowledge in one transaction. Keep client side as a fallback when the server is unreachable.
val productDetailsParams = BillingFlowParams.ProductDetailsParams
.newBuilder()
.setProductDetails(productDetails)
.build()
val flowParams = BillingFlowParams.newBuilder()
.setProductDetailsParamsList(listOf(productDetailsParams))
.setObfuscatedAccountId(hashUserId(currentUser.id))
.build()
val productDetailsParams = BillingFlowParams.ProductDetailsParams
.newBuilder()
.setProductDetails(productDetails)
.setOfferToken(chosenOffer.offerToken)
.build()
val flowParams = BillingFlowParams.newBuilder()
.setProductDetailsParamsList(listOf(productDetailsParams))
.build()
val result = billingClient.launchBillingFlow(activity, flowParams)
if (result.responseCode != BillingResponseCode.OK) {
handleLaunchError(result)
}
You must pass the current Activity. OK here means the dialog was shown, not that payment succeeded. The real result arrives in PurchasesUpdatedListener.
| Code | Meaning | Action |
|---|---|---|
OK | Dialog shown | Wait for listener callback. |
ITEM_ALREADY_OWNED | User owns product or has unacknowledged purchase | Refresh via queryPurchasesAsync() and process it. |
DEVELOPER_ERROR | Bad params, missing offer token, wrong package name | Fix params, check Console listing. |
FEATURE_NOT_SUPPORTED | Device or Play Store does not support the product type | Hide the buy button on this device. |
BILLING_UNAVAILABLE | No Google account or Play Services missing | Prompt user to sign in to Play. |
ITEM_UNAVAILABLE | Not available in region or deactivated | Check Console availability. |
NETWORK_ERROR | Cannot reach Play servers | Retry after delay, do not loop aggressively. |
val listener = PurchasesUpdatedListener { result, purchases ->
when (result.responseCode) {
BillingResponseCode.OK ->
purchases?.forEach { handlePurchase(it) }
BillingResponseCode.USER_CANCELED -> Unit
BillingResponseCode.ITEM_ALREADY_OWNED ->
refreshPurchases()
else -> handleError(result)
}
}
Verify server side. Post purchase.purchaseToken to your backend. Backend calls purchases.products.get (one time) or purchases.subscriptionsv2.get (subs). Check purchaseState == 0, productId, packageName, orderId not seen before, and for subs expiryTimeMillis.
Check purchase.purchaseState. Grant only on PURCHASED. Show pending UI on PENDING. Log on UNSPECIFIED_STATE.
Grant entitlement idempotently. Use purchaseToken as a unique key. A retry, an RTDN, and a second device query must not stack grants.
Acknowledge or consume within 3 days.
// Non consumable and subscriptions
val ackParams = AcknowledgePurchaseParams.newBuilder()
.setPurchaseToken(purchase.purchaseToken)
.build()
billingClient.acknowledgePurchase(ackParams) { r -> /* check OK */ }
// Consumable
val consumeParams = ConsumeParams.newBuilder()
.setPurchaseToken(purchase.purchaseToken)
.build()
billingClient.consumeAsync(consumeParams) { r, t -> /* check OK */ }
Prefer server side acknowledgement. Fall back to client side only after retries fail.
Notify the user. Show specific confirmation ("You now have Premium") immediately from the client. For subs, show next billing date and a link to https://play.google.com/store/account/subscriptions. Return the user to the content they were trying to unlock.
fun handlePurchase(purchase: Purchase) {
when (purchase.purchaseState) {
Purchase.PurchaseState.PENDING -> {
showPendingMessage(purchase)
return
}
Purchase.PurchaseState.PURCHASED -> {
if (!purchase.isAcknowledged) verifyAndGrantAccess(purchase)
}
}
}
Transitions arrive via a later PurchasesUpdatedListener fire, an RTDN on your server, or a fresh queryPurchasesAsync().
startConnection() succeeds. Catches cross device purchases and reinstalls.Add multiple ProductDetailsParams entries to the list. All items must share a product type (subs or inapp). One purchase token covers the bundle, so acknowledge once, then iterate purchase.products to grant every item.
Prove the flow works before calling it done.
launchBillingFlow() returns OK for a real product in an internal test track.PurchasesUpdatedListener fires with OK and a non null purchases list on success, and with USER_CANCELED when the user dismisses the dialog.grantEntitlement. Granting twice with the same token produces the same result (idempotency test).PURCHASED purchase is acknowledged or consumed within 3 days. Monitor unacknowledged count.setOfferToken returns DEVELOPER_ERROR (negative test) and your code surfaces it cleanly.queryPurchasesAsync() is wired to connect, app launch, and onResume.purchase.products yields every product id and each gets an entitlement.