Skip to main content
Registers a handler invoked when Encore’s offer flow completes and a purchase is needed. The handler receives a PurchaseRequest containing the IAP product ID, placement ID, and optional promotional offer ID, and should trigger the purchase via your subscription manager (e.g. RevenueCat, Google Play Billing).
Set onPurchaseRequest before calling placement().show(). If not set, Encore will fall back to a native Play Billing purchase automatically. For best results with 3P subscription managers, set this handler to purchase through your provider directly.

​
Signature

fun onPurchaseRequest(
    handler: suspend (PurchaseRequest) -> Unit
): Encore

​
Parameters

NameTypeDescription
handlersuspend (PurchaseRequest) -> UnitSuspending callback receiving a PurchaseRequest. Trigger your purchase flow here.

​
PurchaseRequest

PropertyTypeDescription
productIdStringThe Google Play product identifier to purchase
placementIdString?The placement that triggered this purchase
promoOfferIdString?Promotional offer identifier, when applicable

​
Returns

Returns the Encore instance for chaining.

​
Usage

​
With RevenueCat

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        Encore.shared.configure(this, apiKey = "pk_your_api_key")

        Encore.shared.onPurchaseRequest { request ->
            // Trigger purchase via your subscription manager
            Purchases.sharedInstance.purchase(
                PurchaseParams.Builder(activity, request.productId).build()
            )
        }
    }
}

​
Chained with onPassthrough

Encore.shared
    .onPurchaseRequest { request ->
        billingManager.purchase(request.productId)
    }
    .onPassthrough { placementId ->
        // User didn't purchase — continue original flow
        handleOriginalAction(placementId)
    }
The handler is a suspend function, so you can call other suspending APIs (like network requests or billing APIs) directly inside it.
When no onPurchaseRequest handler is set, Encore handles purchases via native Play Billing automatically. Use onPurchaseComplete to sync these transactions with providers that don’t auto-detect Play Billing transactions (e.g., Adapty, Qonversion).