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", background: "#0d0f12" } as const;

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

Options

Allowed hosts

A published paywall runs under a Content-Security-Policy Superwall enforces when it serves the page. By default it may talk to Superwall and Stripe and nothing else, so a fetch to your own API is refused by the browser before it reaches the network — no request is sent, and the only sign is a CSP error in the console.

Name the hosts you call and they are permitted:

export default definePaywall({
  name: "Onboarding",
  allowedHosts: ["api.example.com"],
});

Write bare hostnames — https is implied and required. A pasted https://api.example.com is accepted and normalizes to the same thing. An explicit port is kept (api.example.com:8443).

Not accepted: http://, wildcards like *.example.com, paths, and anything that is not a hostname. Every entry is https, with no exception — a served policy should never be able to carry a plaintext origin. Each one goes into that policy verbatim, so it has to be a host you actually call rather than a pattern. superwall push fails and names the entry it could not read, so a typo stops the push instead of becoming a blocked request in production.

A local API

You do not need to name one. superwall dev applies no policy at all, so a fetch to http://localhost:3000 works there whether or not it appears in allowedHosts.

localhost and 127.0.0.1 are rejected outright, and the push says so. The reason is arithmetic rather than policy: a pushed paywall runs on a shopper's device, where localhost is their machine, not yours — so the entry could only widen the policy for everyone in exchange for a request that cannot succeed. To reach a local API from a pushed build, put it behind an https tunnel (ngrok, cloudflared) and name that hostname.

The list travels with the pushed version, like every other setting here, so promote --version rolls it back with the code and two versions can permit different hosts.

Post-purchase

postPurchase is one setting for both platforms; each host reads the part it can act on.

Without a checkout, or with platforms that leave out "web", the type narrows to "dismiss" | "stay" — there is nowhere to redeem or redirect to. A purchase(ref, { postPurchase }) call overrides it for that button.

Platforms

A project can push to several platforms: an iOS app, its Android counterpart, and a web app, all in the same Superwall project. platforms says which of them this paywall is for:

// paywalls/plus-upgrade/config.ts: one directory, shipped to both stores
export default definePaywall({ platforms: ["ios", "android"], products: { … } });

// paywalls/web-upgrade/config.ts: the web app only
export default definePaywall({ platforms: ["web"], checkout: "sheet", products: { … } });

The values are ios, android, and web, and the array is typed, so anything else is a compile error. The project binds one Superwall app per platform in superwall.lock, and every platform listed gets its own dashboard paywall, pushed and promoted independently: a shared directory is one codebase with one live version per platform.

On a single platform the field is optional. Once the project pushes to more than one, every paywall has to say; a push refuses a silent one rather than guess. There is no project-wide default on purpose (config.ts is the whole truth for its paywall); to mirror a set everywhere, share it like any other setting, export const everywhere = { platforms: ["ios", "android", "web"] } as const, and spread it.

A reference stays the same on every platform, but the store product behind it usually doesn't. Give such a slot one id per platform (annual: { ios: "…", android: "…" }, below); each platform's build and version carry their own. Binding a platform to an actual app happens on the first push, see Push, promote & publish.

Presentation

How the native SDK shows the paywall. style is one of fullscreen (default), modal, push, noAnimation, drawer, or popup; the last two take geometry, as percentages of the screen and a corner radius in points:

presentation: { style: "drawer", drawer: { height: 60, cornerRadius: 24 } }
presentation: { style: "popup", popup: { width: 80, height: 60, cornerRadius: 15 } }

Geometry is optional and defaults to a 70% drawer or an 80% × 60% popup with a 15pt radius, the same defaults the editor uses. A zero or negative dimension fails the build. Web builds ignore presentation; the browser is the page.

The style also shapes the paywall's insets: a modal or drawer starts below the status bar, so the top inset is 0 there, and a popup is inset by the SDK on every side. The style is stamped on <html> as data-sw-presentation for CSS that wants to know.

Insets

What the paywall is padded with at each screen edge. The default, "safe-area", keeps every layout and page clear of the status bar, cutout and home indicator on the device the paywall is running on, and clear of nothing on the web:

insets: "safe-area"                            // default — the device's safe area, floored per platform and presentation
insets: "none"                                 // flush to every edge: a full-bleed paywall
insets: 24                                     // pixels, all four edges
insets: "1.5rem"                               // any CSS length
insets: { top: "none", bottom: "safe-area" }   // per edge; an omitted edge stays "safe-area"

Insets never shrink the scroll area: each page scrolls edge to edge and carries the inset as its scroll padding, so content passes under the bars and rests clear of them. Turn an edge off only for something that must rest under the bar. A full-bleed design ("none", or top: "none" for a hero whose top edge is the screen edge) keeps its close button out of the bar with --sw-safe-area-inset-top, which the framework maintains whatever insets says. How the safe area is resolved, and the variables behind it, are in Styling. Insets are a page-level concern and are not part of the version's settings; the SDK is not involved.

Background

Set the color that sits behind the paywall. The string shorthand sets it for light mode; the object form adds a dark-mode color:

background: "#0d0f12"
// or
background: { light: "#ffffff", dark: "#0d0f12" }

Colors are 6- or 8-digit hex (#RRGGBB or #RRGGBBAA). Shorthand like #fff, named colors, and rgb() are rejected at push.

It does two things from one value: native SDKs paint it behind the webview and derive the loading spinner from it, and the web document uses it as the page background, so the color a shopper sees while the paywall loads matches the color it settles on. It takes effect on the next superwall publish; when absent, paywalls fall back to the platform default.

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
  yearly: { ios: "pro_5999_year", android: "pro_5999_year_play" },   // one id per platform
}

A per-platform slot must name every platform in platforms; a push refuses one that can't resolve on a platform it ships to. 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.