> ## Documentation Index
> Fetch the complete documentation index at: https://docs.encorekit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# onPurchaseRequest()

> Handle purchase flow after offer completion

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).

<Warning>
  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.
</Warning>

## Signature

```kotlin theme={null}
fun onPurchaseRequest(
    handler: suspend (PurchaseRequest) -> Unit
): Encore
```

## Parameters

| Name      | Type                                | Description                                                                         |
| --------- | ----------------------------------- | ----------------------------------------------------------------------------------- |
| `handler` | `suspend (PurchaseRequest) -> Unit` | Suspending callback receiving a `PurchaseRequest`. Trigger your purchase flow here. |

### PurchaseRequest

| Property       | Type      | Description                                    |
| -------------- | --------- | ---------------------------------------------- |
| `productId`    | `String`  | The Google Play product identifier to purchase |
| `placementId`  | `String?` | The placement that triggered this purchase     |
| `promoOfferId` | `String?` | Promotional offer identifier, when applicable  |

## Returns

Returns the `Encore` instance for chaining.

## Usage

### With RevenueCat

```kotlin theme={null}
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

```kotlin theme={null}
Encore.shared
    .onPurchaseRequest { request ->
        billingManager.purchase(request.productId)
    }
    .onPassthrough { placementId ->
        // User didn't purchase — continue original flow
        handleOriginalAction(placementId)
    }
```

<Info>
  The handler is a `suspend` function, so you can call other suspending APIs (like network requests or billing APIs) directly inside it.
</Info>

<Note>
  When no `onPurchaseRequest` handler is set, Encore handles purchases via native Play Billing automatically.
  Use [onPurchaseComplete](/publishers/android/sdk-reference/on-purchase-complete) to sync these transactions with providers that don't auto-detect Play Billing transactions (e.g., Adapty, Qonversion).
</Note>