Configuration

Every paywall declares itself in a required config.ts: its dashboard name, its products, and any behavior settings. This file is the whole truth for the paywall — nothing is inherited from anywhere else.

import { definePaywall } from "superwall/config";

export default definePaywall({
  name: "Plus — Annual, 3-day trial",
  products: {
    monthly: "pro_999_month",
    annual: "pro_5999_year",
  },
});

TypeScript is the only validation, so keep the object literal inline — that's what lets the compiler catch typos. If you want to share settings between paywalls, export a plain object and spread it:

// superwall/components/shared-config.ts
export const shared = { transition: "slide", purchaseTimeoutMs: 300_000 } as const;

// paywalls/pro/config.ts
export default definePaywall({ ...shared, name: "Pro", products: { … } });

Options

Presentation

The presentation object controls how the native SDK presents the paywall over your app:

presentation: {
  style: "fullscreen" | "modal" | "push" | "drawer" | "popup" | "noAnimation",  // default "fullscreen"
  condition: "checkUserSubscription" | "always",                                // default "checkUserSubscription"
  drawer: { height, cornerRadius },          // when style === "drawer"
  popup: { width, height, cornerRadius },    // when style === "popup"
}

• style — fullscreen covers the screen, modal uses the platform's modal presentation, push pushes onto the navigation hierarchy, drawer rises from the bottom edge to the height you set, popup floats as a centered window, and noAnimation presents modally without animating.
• condition — with the default checkUserSubscription, the SDK skips presentation for users who are already subscribed. Use always to show the paywall regardless.
• drawer and popup take sizing options that only apply to their matching style.

Products

Products are slots. The key is the reference your code uses; the value is the store identifier:

products: {
  annual: "pro_5999_year",                    // shorthand
  monthly: { productId: "pro_999_month" },    // same thing
}

Your components read them by reference — getProduct("annual"), purchase("annual") — and the references are typed, so a typo is a compile error. Web/Stripe products put the Stripe price inside the identifier using the {test|live}:price_…:{offer} format.

Product data — price, period, trial — never appears in this file. It's store-owned and arrives at runtime; a reference the dashboard has no product for renders undefined variables and blocks publishing. The full story, including how to read product variables safely, is in Products.

Trial reminder notifications

Declare a local notification and the SDK schedules it when a trial actually starts — the paywall doesn't need to be open when it fires:

notifications: {
  trialReminder: {
    title: "Your trial ends tomorrow",
    body: "Keep Pro, or cancel in Settings — no charge either way.",
    beforeTrialEndDays: 1,        // default 1
  },
},

title, subtitle, and body accept message keys (resolved through t()) or literal copy. For full control, pass a function instead — it receives { trialEndDate, product, t, locale } and returns { title, body, delayMs }, or null to skip the notification entirely. The trial reminders example shows both forms — see Examples.

Experimenting without rebuilds

Variables are never declared in this file: everything the paywall reads — useVariables(), product variables, trial eligibility — is supplied by your app and the store at runtime, and the studio can override all of it live while you preview. Write your paywall to read variables defensively and every one of them becomes experimentable from the dashboard, no rebuild required. See Variables & personalization.