Display a paywall

A paywall is the screen a customer sees. A location is the stable slug your app asks for, such as onboarding or settings-upsell. You publish and assign paywalls to locations in Studio — see Paywall locations. This page covers presenting them with the React Native SDK.

Present it

usePaywallByLocation preloads the paywall assigned to the location and returns show():

const paywall = voidhash.usePaywallByLocation("settings-upsell", {
  onPurchase: ({ productId }) => {
    console.log("Purchased", productId);
  },
  onRestore: () => {
    console.log("Purchases restored");
  },
  onError: (error, { action }) => {
    console.warn(`Paywall ${action} failed`, error);
  },
});

const result = await paywall.show();

show() never rejects. It resolves to a ShowPaywallResult whose status names the outcome:

Purchase and restore failures are reported through the hook's onError callback, not through show() — by then the paywall is already on screen.

Hosted paywalls send purchase and restore actions through the SDK. After a successful transaction, Voidhash refreshes the person snapshot and dismisses the paywall.

Fall back when nothing was shown

Clearing or archiving a location in Studio makes future presentations return not_assigned. Keep a fallback for important entry points:

const result = await paywall.show();

if (result.status !== "shown") {
  navigation.navigate("Plans");
}

Preloading

The hook preloads this location's paywall so show() presents without waiting on the network. Preload failures are reported through the onPreloadError option:

onPreloadError is a reporting hook, not a recovery path: the SDK retries on the next app foreground and again on show(), and a show() that hits the same failure returns a failed result instead of calling the callback.

Next steps

• Publish and change locations safely
• Check access after a purchase
• Build a custom purchase screen