Paywalls

Create and customize subscription paywalls

A paywall is a fullscreen UI that you design in Helium and display to users in your app. It’s built with React, rendered in a WebView, and can be fully customized — layout, copy, images, animations, products, and translations. Paywalls are the visual surface of your monetization strategy; workflows and experiments decide when to show them, but the paywall is what the user sees.

---

Anatomy of a Paywall

Field	Description
Paywall Name	A human-readable label (e.g., “Annual Upsell — Dark Mode”). Max 100 characters.
Description	A short summary of the paywall’s purpose. Max 250 characters.
Product Buckets	The products offered on this paywall — each bucket maps to a plan (monthly, annual, etc.) across platforms.

---

How Paywalls Are Rendered

Paywalls are bundled into a single web file and rendered inside a native WebView:

1. Your app’s SDK receives a trigger and resolves it to a workflow.
2. The SDK loads this bundle in a WKWebView (iOS) or WebView (Android).
3. The paywall communicates back to the native app via a bridge — handling subscribe, dismiss, restore purchases, and product selection events.

This architecture means paywalls support anything a web page can: CSS animations, custom fonts, Lottie animations, responsive layouts, and dynamic product data. And your paywall can interact directly with the native functions of your mobile frameworks.

---

Creating a Paywall

Paywalls can be created in four ways:

Method	Description
From scratch	Start with a blank canvas and build your UI in the code editor.
From a template	Pick a pre-built starter template and customize it.
From a screenshot	Upload a screenshot of a paywall you like — Helium’s AI generates React code matching the design.
From Figma	Paste a Figma URL — Helium converts the design into a working paywall.

All creation methods follow the same flow:

1. Enter a name and description.
2. Select product buckets (and choose initial iOS/Android/Stripe products).
3. Helium generates the initial files and opens the editor.

---

The Paywall Editor

The editor is a live coding environment powered by Sandpack (CodeSandbox’s embeddable bundler). You edit React code on the left and see a real-time preview on the right.

Editable files

File	What you edit
App.tsx	The paywall’s UI — layout, styling, components, animations. This is the main file you work in.
paywallConfig.tsx	Initial product selection logic, scroll settings, platform-specific behavior.
localizations.ts	Translation strings for every locale. (See [Localization] for the full localization system.)

Auto-generated files (read-only in most cases)

File	Purpose
products.tsx	Product prices, offers, and metadata. Regenerated when you change territory, products, or offer settings.
index.html	The HTML shell — includes font imports and global setup.
withPaywallState.tsx	A higher-order component that provides paywall state (subscribing, restoring, product selection) to your UI.

Preview features

• Device selector — Preview on different phone models and sizes.

• Platform toggle — Switch between iOS and Android to see platform-specific products.

• Territory picker — Preview localized prices for any App Store or Play Store territory.

• Offer simulation — Toggle intro offer eligibility to preview trial and promotional pricing.

---

Versioning

Every paywall has a version history. Each save creates a new version, building a timeline of changes.

Version statuses

Status	Meaning
Draft	A saved version that hasn’t been published yet. Only visible in the editor.
Published	The live version served to users via the SDK. Only one published version exists per paywall at a time.
Archived	A previously published version that was superseded. Kept for history and rollback.

How it works

• Every save (manual or autosave) creates a new draft version.

• The version stores all paywall files, product bucket references, font references, and a CRDT snapshot.

• Each version tracks its parent version, forming a version tree.

• You can browse version history and see who saved each version and when.

---

Saving

Paywalls support both manual and automatic saving:

Trigger	Behavior
Manual save	Click “Save” or use the keyboard shortcut. Creates a draft version immediately.
Autosave (interval)	Periodic saves while you’re editing. Debounced to avoid excessive version creation.
Autosave (new paywall)	Automatic first save when you create a new paywall.

Each save bundles the code into a deployable web file. This means your draft is always previewable — bundling doesn’t wait for publish.

---

Publishing

Publishing makes a draft version live. When you publish:

1. Validation — Helium checks for issues like hardcoded prices (prices should come from product data, not be typed into the UI).
2. Status update — The draft becomes published. The previously published version becomes archived.
3. SDK sync — The bundle_url on the paywall record is updated so the SDK fetches the new version.
4. History entry — A record is added to paywall_publish_history with who published and when.

Publishing is instant — once published, the next SDK fetch gets the new bundle. There’s no deploy step or propagation delay.

---

Products and Buckets

Paywalls don’t reference raw product IDs. Instead, they reference product buckets — cross-platform containers that hold iOS, Android, and Stripe products for a single logical offering.

• A paywall’s product_bucket_ids lists which buckets it uses.

• The editor resolves buckets into a products.tsx file with localized pricing for the selected territory.

• When the SDK loads the paywall, it receives the product references and handles purchasing natively.

---

How Paywalls Connect to Workflows

Paywalls are used in workflows in three ways:

• Control paywall — Every workflow has a default paywall shown when no targeting rules match.

• Audience targeting — A workflow rule can map an audience directly to a specific paywall.

• Experiment variants — Paywalls serve as variants in A/B tests, each receiving a share of traffic.

Only published paywalls can be assigned to workflows and experiments. Draft-only paywalls won’t appear in selection lists.

---

Second-Try Paywalls

A paywall can optionally have a second-try paywall — a follow-up paywall shown if the user dismisses the first one. This is configured via paywall settings field and allows for a softer re-engagement attempt (e.g., a discounted offer after the user declines the full-price paywall).

Second-try paywalls can either appear after a paywall dismiss or after a subscription cancel event.

---

Localization

Paywalls have a full localization system with per-locale translations, territory-aware pricing, and right-to-left layout support. Translation keys are defined and managed through the editor. Localizely support is available for localization management as well.

See [Localization] for the complete localization documentation.

---

Key Rules

• Paywall names can be up to 100 characters.

• Only published paywalls can be used in workflows and experiments.

• Only one published version exists per paywall at a time.

• Publishing runs validation — hardcoded prices and other issues can block publish.

• Paywalls cannot be deleted if they’re referenced by a workflow.

• Every save bundles the code — drafts are always previewable.

• Product data is auto-generated from buckets — don’t hardcode prices in your UI.

• Paywalls render in a WebView — they support standard web features (CSS, fonts, animations, Lottie).

---

Common Patterns

Pattern	Description
Single-plan paywall	One product bucket, one CTA. Clean and focused conversion.
Multi-plan paywall	Two or three product buckets (monthly, annual, lifetime) with a plan selector. The most common layout.
Free trial emphasis	Highlight the trial period prominently. Use introOfferEligible from product data to conditionally show trial messaging.
Feature comparison	List free vs. premium features with a comparison table. Common for productivity apps.
Seasonal promotion	Duplicate an existing paywall, update the copy and styling for a holiday sale, run it as an experiment.
Second-try offer	Main paywall at full price; second-try paywall with a discount or extended trial for users who dismiss.
Localized paywall	Same layout, different copy per locale. Prices are automatically localized from product buckets; translate the UI text in localizations.ts.

---