Presenting Offers

Overview

Encore allows you to present targeted offers to users in exchange for rewards (free trials, discounts, credits) at critical moments like cancellation flows or feature paywalls. The SDK uses a callback pattern — you register purchase and passthrough handlers, then call show() wherever you need an offer.

Present Offers

Presenting an Encore offer is a single line:

const result = await Encore.placement('cancellation_flow').show();

Important: When presenting offers in critical flows (like cancellation), your onPassthrough handler ensures users are never blocked from completing their intended action.

Handle Offer Results

Choosing your integration shape: This page shows the handler pattern. If your call site has direct access to purchase logic, the async-result pattern is often cleaner. See Integration Patterns for the decision tree and React Native Integration Patterns for TypeScript examples.

Register handlers that tell the SDK how to complete purchases and what to do when a user dismisses. Register these once at app startup, after configure() and registerCallbacks().

Register `onPurchaseRequest`

Called when a user accepts an offer. Use this to trigger a purchase via your billing library.

You must call completePurchaseRequest() in every code path — both success and failure. Failing to do so will block the SDK from presenting future offers.

const unsubscribe = Encore.onPurchaseRequest(async ({ productId, placementId }) => {
  try {
    await yourBillingLibrary.purchase(productId);
    await Encore.completePurchaseRequest(true);
  } catch (error) {
    await Encore.completePurchaseRequest(false);
  }
});

See onPurchaseRequest() for RevenueCat, react-native-iap, and custom examples.

Register `onPassthrough`

Called when the user dismisses the offer or no offers are available. Use this to resume the user’s original action (e.g., proceed with cancellation).

const unsubscribe = Encore.onPassthrough(({ placementId }) => {
  // Resume your original user flow
});

`onPurchaseComplete` (Optional)

Fires after a native purchase completes (when no onPurchaseRequest handler is set on the native side). Use this to sync purchase state with your subscription manager.

const unsubscribe = Encore.onPurchaseComplete(({ productId, transactionId }) => {
  // Sync purchase state
});

Summary

Callback	When it fires	Required?
`onPurchaseRequest`	User accepts the offer	Yes
`onPassthrough`	User dismisses or no offers available	Yes
`onPurchaseComplete`	Purchase finishes natively	Optional

Full Example

import Encore, { EncoreProvider } from '@tryencorekit/react-native';

// In your App component
export default function App() {
  return (
    <EncoreProvider apiKey="pk_your_api_key">
      <MainApp />
    </EncoreProvider>
  );
}

// In a screen component
function SubscriptionScreen() {
  useEffect(() => {
    const unsub1 = Encore.onPurchaseRequest(async ({ productId }) => {
      try {
        await billingService.purchase(productId);
        await Encore.completePurchaseRequest(true);
      } catch (error) {
        await Encore.completePurchaseRequest(false);
      }
    });

    const unsub2 = Encore.onPassthrough(({ placementId }) => {
      proceedWithCancellation();
    });

    return () => {
      unsub1();
      unsub2();
    };
  }, []);

  const handleCancel = async () => {
    await Encore.placement('cancellation_flow').show();
  };

  return (
    <Button title="Cancel Subscription" onPress={handleCancel} />
  );
}

Next Steps

SDK Reference - Complete API documentation

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

Overview

Present Offers

Handle Offer Results

Register `onPurchaseRequest`

Register `onPassthrough`

`onPurchaseComplete` (Optional)

Summary

Full Example

Next Steps

​Overview

​Present Offers

​Handle Offer Results

​Register onPurchaseRequest

​Register onPassthrough

​onPurchaseComplete (Optional)

​Summary

​Full Example

​Next Steps

Overview

Present Offers

Handle Offer Results

Register `onPurchaseRequest`

Register `onPassthrough`

`onPurchaseComplete` (Optional)

Summary

Full Example

Next Steps