rc-purchase-flow

Purchase Flow

A RevenueCat purchase on Android is two lines of code. The SDK handles the billing params, the Play sheet, the purchase token round trip, server side verification, and acknowledgment. You decide which package to pass in and what to do with the returned entitlements.

Phase 1: Understand what awaitPurchase() does

One call to Purchases.sharedInstance.awaitPurchase(params) runs six steps under the hood. You do not write any of this.

Step	What happens
1	Builds BillingFlowParams with the correct ProductDetailsParams from your Package
2	Calls BillingClient.launchBillingFlow() against the activity you passed
3	Suspends until the PurchasesUpdatedListener result arrives
4	If OK, posts the Play purchase token to the RevenueCat backend
5	Backend verifies via purchases.subscriptionsv2.get or purchases.products.get
6	SDK acknowledges (subs or non-consumables) or consumes (consumables) within the 3 day Google window

The call returns PurchaseResult(storeTransaction, customerInfo). Retriable failures are retried automatically.

See the Purchase Flow chapter on revenuecat.com for the six-step diagram and the full picture.

Phase 2: Prepare the package

You need a Package from offerings before you can purchase. Fetch offerings, let your UI pick one, and hold the activity.

val offerings = Purchases.sharedInstance.awaitOfferings()
val pkg = offerings.current?.monthly ?: return

If you need a specific offer instead of the default, resolve a SubscriptionOption and pass that to PurchaseParams.Builder instead of the package.

val option = pkg.product.subscriptionOptions
    ?.firstOrNull { it.tags.contains("promo_50_off") }
    ?: pkg.product.defaultOption
    ?: return

For EU personalized pricing, chain .isPersonalizedPrice(true) on the builder so Play shows the customized price notice.

Phase 3: Execute the purchase

Build the params, await the purchase, read customerInfo to gate access, and handle the two expected error branches.

try {
    val result = Purchases.sharedInstance.awaitPurchase(
        PurchaseParams.Builder(activity, pkg).build()
    )
    val customerInfo = result.customerInfo
    if (customerInfo.entitlements["pro"]?.isActive == true) {
        navigateToApp()
    }
} catch (e: PurchasesTransactionException) {
    when {
        e.userCancelled -> { /* backed out, do nothing */ }
        e.error.code == PurchasesErrorCode.ProductAlreadyPurchasedError ->
            showMessage("You already have this subscription")
        else -> showError(e.error.message)
    }
}

Rules for this block:

• PurchaseResult is @Poko. Access fields as result.customerInfo and result.storeTransaction. Do not destructure with val (transaction, customerInfo) = result.
• customerInfo.entitlements["<id>"]?.isActive == true is the gate. Do not check storeTransaction to decide access.
• PurchasesTransactionException is the only exception type thrown by awaitPurchase. Catch it, branch on userCancelled first, then on e.error.code.
• User cancellation is not an error to surface. Swallow it.

If you prefer callbacks over coroutines, purchaseWith(params, onError, onSuccess) is the equivalent entry point.

Phase 4: Inspect StoreTransaction only if you need it

result.storeTransaction is available but usually unused. customerInfo is the source of truth for entitlements. If you need transaction level data for logging or your own backend:

Field	Type	Notes
orderId	String?	Null for restored purchases
purchaseToken	String	Raw Play purchase token
productIds	List<String>	Product IDs in the transaction
purchaseTime	Long	Epoch millis
type	ProductType	SUBS or INAPP

Phase 5: Restore on reinstall or device switch

Restore runs queryPurchasesAsync(), posts everything found to RevenueCat, and returns the fresh CustomerInfo. Gate access the same way you do after a purchase.

try {
    val customerInfo = Purchases.sharedInstance.awaitRestore()
    if (customerInfo.entitlements["pro"]?.isActive == true) {
        navigateToApp()
    } else {
        showMessage("No active purchases found")
    }
} catch (e: PurchasesException) {
    showError(e.error.message)
}

Note the exception type. awaitRestore() throws PurchasesException, not PurchasesTransactionException. There is no userCancelled flag to check because no billing sheet is shown.

Exception types at a glance

Call	Thrown exception	Has userCancelled?
awaitPurchase(params)	PurchasesTransactionException	Yes
awaitRestore()	PurchasesException	No

References

• Full chapter