onPurchaseRequest()

Registers a handler invoked when Encore’s offer flow completes and a purchase is needed. The handler receives a PurchaseRequest containing the product ID, placement ID, and optional promotional offer ID. Use it to trigger the purchase via your subscription manager (e.g. StoreKit, RevenueCat).

Set onPurchaseRequest before calling placement(_:).show(). If not set, Encore falls back to a native StoreKit purchase automatically. For best results with 3P subscription managers, set this handler to purchase through your provider directly.

Signature

@discardableResult
public func onPurchaseRequest(_ handler: @escaping (PurchaseRequest) async throws -> Bool) -> Encore

Return true on success. Returning true tells Encore the purchase completed, and Encore auto-dismisses the offer sheet. Return false (or throw) when the purchase was cancelled or failed — the sheet stays up so the user can retry. A thrown error is caught by the SDK and treated as false.A legacy ... async throws -> Void overload also exists but is deprecated: it can’t signal success/failure reliably, so dismiss behavior is less predictable. Always use the Bool-returning form.

Parameters

Name	Type	Description
`handler`	`(PurchaseRequest) async throws -> Bool`	Async throwing callback receiving a `PurchaseRequest`. Trigger your purchase flow here and return `true` if it succeeded.

PurchaseRequest Properties

Property	Type	Description
`productId`	`String`	The App Store product identifier to purchase
`placementId`	`String?`	Which placement triggered this purchase, if any
`promoOfferId`	`String?`	Promotional offer identifier to apply, or `nil` for standard purchases

Returns

@discardableResult — returns the Encore instance for chaining (.onPurchaseRequest { … }.onPassthrough { … }).

When It Fires

Scenario	Fires?
User accepts an offer	Yes
User dismisses without purchasing	No — see onPassthrough()
No offer available for this user	No — see onPassthrough()

Usage

StoreKit
RevenueCat
Adapty
Qonversion
Custom

Encore.shared.onPurchaseRequest { purchaseRequest in
    guard let product = try await Product.products(for: [purchaseRequest.productId]).first else {
        return false
    }
    let result = try await product.purchase()
    guard case .success(let verification) = result,
          case .verified(let transaction) = verification else {
        return false  // cancelled, pending, or unverified — keep the sheet up
    }
    await transaction.finish()
    return true  // verified purchase — dismiss the sheet
}

Encore.shared.onPurchaseRequest { purchaseRequest in
    let products = try await Purchases.shared.products([purchaseRequest.productId])
    guard let product = products.first else { return false }
    let result = try await Purchases.shared.purchase(product: product)
    return !result.userCancelled
}

Encore.shared.onPurchaseRequest { purchaseRequest in
    let products = try await Adapty.getPaywallProducts(paywall: paywall)
    guard let product = products.first(where: { $0.vendorProductId == purchaseRequest.productId }) else {
        return false
    }
    let result = try await Adapty.makePurchase(product: product)
    return !result.isPurchaseCancelled
}

Encore.shared.onPurchaseRequest { purchaseRequest in
    let result = try await Qonversion.shared().purchaseProduct(productId: purchaseRequest.productId)
    return !result.isCancelled
}

Encore.shared.onPurchaseRequest { purchaseRequest in
    // purchaseRequest.productId — App Store product ID to purchase
    // purchaseRequest.placementId — which placement triggered this (optional)
    // purchaseRequest.promoOfferId — promotional offer to apply (optional)
    let didSucceed = try await yourManager.purchase(purchaseRequest.productId)
    return didSucceed   // true → Encore dismisses the offer sheet
}

Chained with onPassthrough

Encore.shared
    .onPurchaseRequest { purchaseRequest in
        guard let product = try await Product.products(for: [purchaseRequest.productId]).first else {
            return false
        }
        let result = try await product.purchase()
        if case .success = result { return true }
        return false
    }
    .onPassthrough { placementId in
        // User didn't purchase — continue original flow
        proceedWithCancellation()
    }

The handler is an async throws -> Bool function, so you can await other async APIs (StoreKit, network requests) directly inside it. Return true once the purchase succeeds so Encore dismisses the offer sheet.

When no onPurchaseRequest handler is set, Encore handles purchases via native StoreKit 2 automatically. Use onPurchaseComplete to sync these transactions with providers that don’t auto-detect StoreKit transactions (e.g., Adapty, Qonversion).

Getting Started

iOS SDK

Android SDK

Flutter SDK

React Native SDK

Capacitor SDK

Kotlin Multiplatform SDK

Web SDK

Integration Patterns

Automated Messaging

Offer Catalog

Offers API

Signature

Parameters

PurchaseRequest Properties

Returns

When It Fires

Usage

Chained with onPassthrough

​Signature

​Parameters

​PurchaseRequest Properties

​Returns

​When It Fires

​Usage

​Chained with onPassthrough

Signature

Parameters

PurchaseRequest Properties

Returns

When It Fires

Usage

Chained with onPassthrough