One Time Products

One Time Products

Build a complete Google Play one time product integration with Play Billing Library 9.x. This skill walks through the full lifecycle: querying, launching, handling pending state, and finishing with either consume or acknowledge.

Phase 0: Intent

Confirm what you are building before writing code. Answer these questions:

• What product type is this? Consumable (repeatable like coins) or non consumable (one time like remove ads)?
• Where does fulfillment happen? Server side verification plus server side consume or acknowledge is the reliable pattern. Client side is acceptable only during early development.
• Which PBL version is the app on? PBL 9.x is assumed. Pending purchases for one time products are enabled explicitly by passing PendingPurchasesParams.newBuilder().enableOneTimeProducts() to enablePendingPurchases() (required since PBL 8.0; the parameterless overload was removed in 8.0).
• Do you need multi quantity, pre order, or multiple offers on the same product?

If any answer is unclear, stop and gather the requirements. Do not ship a purchase flow with ambiguous fulfillment rules.

Phase 1: Discovery

Gather the facts that drive the implementation.

Choose naming up front. Good patterns: coins_100, remove_ads, level_pack_desert. Avoid product_1 or item_a. Product IDs are permanent and cannot be reused after deletion.

Phase 2: Plan

Decide consumable vs non consumable. The choice drives which API you call after granting entitlement.

Google Play does not enforce this split at the product configuration level. A product becomes consumable because your code calls consumePurchase() on it.

Plan the end to end flow before writing code:

1. Query products with queryProductDetailsAsync().
2. Display products using formattedPrice.
3. Launch purchase with launchBillingFlow() from an Activity.
4. Receive result through PurchasesUpdatedListener.
5. Route by purchaseState: PURCHASED, PENDING, or UNSPECIFIED_STATE.
6. Verify on your server with the Google Play Developer API.
7. Grant entitlement.
8. Consume (consumable) or acknowledge (non consumable) within 3 days. Aim for seconds.
9. Catch missed purchases with queryPurchasesAsync() on launch and resume.

Phase 3: Execute

Query product details

One time products use ProductType.INAPP. Always check the BillingResult response code before reading the list.

suspend fun queryOneTimeProducts(
    billingClient: BillingClient
): List<ProductDetails> {
    val productList = listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("coins_100")
            .setProductType(ProductType.INAPP)
            .build()
    )
    val params = QueryProductDetailsParams.newBuilder()
        .setProductList(productList)
        .build()
    val result = billingClient.queryProductDetails(params)
    return result.productDetailsList.orEmpty()
}

Use formattedPrice directly. It is already localized.

fun displayProduct(productDetails: ProductDetails) {
    val name = productDetails.name
    val description = productDetails.description
    val price = productDetails
        .oneTimePurchaseOfferDetails
        ?.formattedPrice
}

Launch the purchase flow

launchBillingFlow() needs an Activity. Only one flow can be active at a time.

fun launchPurchase(
    activity: Activity,
    billingClient: BillingClient,
    productDetails: ProductDetails
): BillingResult {
    val productDetailsParams =
        BillingFlowParams.ProductDetailsParams
            .newBuilder()
            .setProductDetails(productDetails)
            .build()
    val flowParams = BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            listOf(productDetailsParams)
        )
        .build()
    return billingClient.launchBillingFlow(
        activity, flowParams
    )
}

Attach hashed identifiers for fraud detection and backend correlation. Never pass raw user IDs.

val flowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(listOf(productDetailsParams))
    .setObfuscatedAccountId(hashedUserId)
    .setObfuscatedProfileId(hashedProfileId)
    .build()

Receive the purchase result

private val listener =
    PurchasesUpdatedListener { result, purchases ->
        when (result.responseCode) {
            BillingResponseCode.OK ->
                purchases?.forEach { handlePurchase(it) }
            BillingResponseCode.USER_CANCELED -> {
                // User dismissed the purchase dialog
            }
            else -> {
                // Log and surface an error
            }
        }
    }

Route by purchase state

Never grant, consume, or acknowledge a PENDING purchase.

fun handlePurchase(purchase: Purchase) {
    when (purchase.purchaseState) {
        Purchase.PurchaseState.PURCHASED ->
            verifyAndGrantEntitlement(purchase)
        Purchase.PurchaseState.PENDING ->
            showPendingMessage(purchase)
        Purchase.PurchaseState.UNSPECIFIED_STATE -> {
            // Log and investigate
        }
    }
}

Consume a consumable

consumePurchase() finalizes the purchase and removes it from history so the user can buy it again. Consume from your server when possible.

suspend fun consumePurchase(
    billingClient: BillingClient,
    purchaseToken: String
) {
    val params = ConsumeParams.newBuilder()
        .setPurchaseToken(purchaseToken)
        .build()
    val result = billingClient.consumePurchase(params)
    if (result.billingResult.responseCode
        == BillingResponseCode.OK
    ) {
        // Purchase consumed
    }
}

Acknowledge a non consumable

Check purchase.isAcknowledged first. Calling acknowledge twice returns an error.

suspend fun acknowledgePurchase(
    billingClient: BillingClient,
    purchaseToken: String
) {
    val params = AcknowledgePurchaseParams.newBuilder()
        .setPurchaseToken(purchaseToken)
        .build()
    val result = billingClient.acknowledgePurchase(params)
    if (result.billingResult.responseCode
        == BillingResponseCode.OK
    ) {
        // Purchase acknowledged
    }
}

Handle multi quantity

Always read purchase.quantity. For single quantity purchases the value is 1, so the code stays compatible.

fun handleMultiQuantityPurchase(purchase: Purchase) {
    val quantity = purchase.quantity
    grantCoins(userId, quantity * COINS_PER_PACK)
    consumePurchase(billingClient, purchase.purchaseToken)
}

Launch a specific offer

When a product has multiple offers, pass the offerToken from the chosen offer.

fun launchPurchaseWithOffer(
    activity: Activity,
    billingClient: BillingClient,
    productDetails: ProductDetails,
    offerToken: String
): BillingResult {
    val params = BillingFlowParams.ProductDetailsParams
        .newBuilder()
        .setProductDetails(productDetails)
        .setOfferToken(offerToken)
        .build()
    val flowParams = BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(listOf(params))
        .build()
    return billingClient.launchBillingFlow(
        activity, flowParams
    )
}

Catch missed purchases

Call queryPurchasesAsync() on app launch, on BillingClient reconnect, and on onResume().

suspend fun queryExistingPurchases(
    billingClient: BillingClient
): List<Purchase> {
    val params = QueryPurchasesParams.newBuilder()
        .setProductType(ProductType.INAPP)
        .build()
    val result = billingClient.queryPurchasesAsync(params)
    return result.purchasesList
}

Back end verification

The server flow for each PURCHASED purchase:

1. Receive the purchase token from the client.
2. Call the Google Play Developer API purchases.products.get with the token.
3. Confirm the purchase state, product ID, and expected price.
4. Record the entitlement in your database.
5. Call purchases.products.consume or purchases.products.acknowledge.
6. Return success to the client only after the finalize call succeeds.

Pair this with RTDN handling so your backend stays in sync with pending transitions and refunds.

Phase 4: Verify

Run these checks before you ship.

Common pitfalls to scan for:

• Only relying on PurchasesUpdatedListener and skipping queryPurchasesAsync().
• Consuming before the server recorded the entitlement.
• Granting entitlement on PENDING.
• Hardcoding prices in the UI.
• Ignoring BillingClient disconnects. Wrap calls in retry logic and check isReady.
• Generic product IDs like product_1.
• Skipping server side verification entirely.

References

• Full chapter