Troubleshooting / FAQ

Why are offers no longer showing after the first purchase?

completePurchaseRequest wasn’t called. This is the single most common Encore integration bug.

Inside the purchase flow you must call completePurchaseRequest(true | false) on every path — success and failure. If you don’t (a thrown billing error that skips the call is the usual culprit), Encore believes a purchase is still in flight and blocks all future offers.

The fix is to use useEncoreCallbacks — it wraps your purchase in a try/catch and calls completePurchaseRequest for you on both paths:

useEncoreCallbacks(Encore, {
  purchase: async (productId) => billing.purchase(productId),
  // completePurchaseRequest(true) on success, (false) on throw — handled for you
});

If you register onPurchaseRequest by hand instead, you own that guarantee — don’t forget the catch.

Why do some install docs say `@encorekit/react-native`?

Encore’s install page references @encorekit/react-native, while the configure / present-offers / user-management pages all use @tryencorekit/react-native.

Use @tryencorekit/react-native everywhere — that’s the published native package (npm). The @encorekit/react-native reference is a known doc inconsistency; treat it as a typo.

npm install @tryencorekit/react-native   # ✅ correct (the real native SDK)
npm install react-native-encore-mock     # ✅ the mock-first kit (these docs)
# npm install @encorekit/react-native     # ❌ wrong (stale install-page name)

What is `apiKey="pk_your_api_key_here"`?

It’s a placeholder for your Encore publishable key (pk_ = client-side key, safe to ship). Get a real one from the Encore dashboard.

In mock mode it’s inert — no network, no validation; the mock just stores and logs a masked copy. Any non-empty string works. It only becomes a real credential when you set USE_MOCK = false and switch to the native SDK. Don’t remove the prop entirely (the provider passes it to configure()); just leave a placeholder.

Prefer not to hard-code it? Source it from an env file per build with react-native-config and use separate dev/prod keys.

Do I need TypeScript type shims?

No. react-native-encore-mock ships its own types, so TS consumers get full typing in mock mode. When you switch to @tryencorekit/react-native, the real package ships its types — nothing to add or delete.

I flipped `USE_MOCK = false` but the app crashes on launch

Live mode loads the native module, which requires:

@tryencorekit/react-native installed, and
a native rebuild — cd ios && pod install then a fresh npm run ios/run-android (bare RN), or npx expo prebuild && npx expo run:ios (Expo). A Metro refresh is not enough for native modules.

See Mock vs Live Mode.

Is the user ever charged by Encore?

No. Encore presents the offer and reports the result. For paid offers your billing library performs the purchase inside your purchase fn; for sponsored offers the partner brand pays and the result comes back as status: 'completed' with no billing call at all.

Customizing for Production