Creating Paywalls

Paywall Variables

Use variables in Superwall paywalls to reuse values, adapt to device size and format prices. Covers device, product, user and custom variables.

To add or edit variables, click the Variables button from the sidebar:

Variables allow you to reuse common values, adapt to the device's characteristics (such as size or color scheme), and do things like dynamically hide or how components. All of these scenarios can be achieved using variables in conjunction with our dynamic values editor:

  • Presenting or hiding a bottom sheet of products.
  • Changing the padding of several elements based on the device's available width.
  • Formatting the price of a product based on different parameters, such as trial availability.

By default, Superwall has three different type of variables for use:

  • Device: Relates to the device, the app's install date, bundle ID and more.
  • Product: Represents the products added to the paywall, and their properties. In addition, there are variables for the selected product in addition to the primary, secondary or tertiary product.
  • User: User-specific values, such as their alias ID.

While those will allow you to cover several cases, you can also add your own custom variables too.

Variables dealing with any product period, such as someProduct.period, someProduct.periodly, and other similar variables, can localize automatically now. Learn more here.

Using Variables

You primarily use variables in the component editor and with dynamic values. When using a variable in text, follow the Liquid syntax to reference one: {{ theVariable }}. For example, to reference a variable in some text, you would:

  1. Select the text component.
  2. Under Text -> click "+ Add Variable".
  3. Then, drill down or search for the variable or its corresponding property.
  4. Click on it, and it'll be added to your text and correctly formatted.

To use a variable with a component property, click on the property and choose Dynamic:

The dynamic values editor will appear. Next to then:, choose your variable and click Save:

Above, the "padding" variable was used. You can ignore the if/then rules above if you simply want to apply a variable, but to dynamically enable or disable them — you can set conditions accordingly. Read the docs over dynamic values to learn more.

You can also hover a property and hold down the Option/Alt key to bring up the dynamic values editor.

Clearing variables

To remove a variable that's in use, click the property or gear icon (which will be purple when a variable is being used) and selected Clear.

Stock variable documentation

Below are all of the stock variables and their types. You don't have to memorize any of these — when the variable picker shows, each of the correct liquid syntax appears above every variable, and it be will auto-inserted for you when selected.

PropertyTypeExample
App Install DateText2024-04-11 02:40
.918000
App User IdText$SuperwallAlias
App VersionText1.0.2
Bundle IdTextcom.yourOrg.yourApp
Days Since InstallNumber0
Days Since Last Paywall ViewNumber
Device Currency CodeTextAED
Device Currency SymbolTextAED
Device Language CodeTexten
Device LocaleTexten_AE
Device ModelTextiPhone14
Font ScaleNumber1.0
Font SizeNumber16
Interface StyleTextlight
Interface TypeTextiphone, ipad, mac. Returns "mac" for Mac Catalyst, "ipad" for iPad apps on mac.
Is Low Power Mode EnabledNumber0
Is MacNumber0
Local DateText2024-05-02
Local Date TimeText2024-05-02T21:31
Local TimeText21:31
Minutes Since InstallNumber7
Minutes Since Last Paywall ViewNumber1
OrientationString"landscape" or "portrait"
Os VersionText17.4.1
PlatformTextiOS
Public Api KeyTextpk_ccdfsriotuwiou23435
Radio TypeTextWiFi
Total Paywall ViewsNumber10
Utc DateText2024-05-02
Utc Date TimeText2024-05-02T17:31
Utc TimeText17:31
Vendor IdTextCC93GCD-ESB6-4DFF-A165-0963D0257221
View Port BreakpointTextX-Small/Small/Medium/Large/Extra Large/ Extra extra large
View Port WidthNumber844
View Port HeightNumber390

Reference any of the variables above by using the device variable. For example, if you were creating a filter or dynamic value based off whether or not the device was a Mac, you'd write {{ device.isMac }}.

PropertyTypeExample
Currency CodeTextUSD
Currency SymbolText$
Daily PriceText$0.26
IdentifierTextefc.1m799.3dt
Billing Plan TypeTextMONTHLY
Is Billing Plan AvailableBoolTrue/False
Lanauge CodeTexten
LocaleTexten_US@currency=USD
Localized PeriodText1m
Monthly PriceText$10.00
PeriodTextmonth
Period AltText1m
Period DaysText30
Period MonthsText1
Period WeeksText4
Period YearsText0
PeriodlyTextmonthly
PriceText$7.99
Raw PriceText7.99
Raw Trial Period PriceText0
Trial Period Daily PriceText$0.00
Trial Period DaysText0
Trial Period End DateTextMay 2, 2024
Trial Period Monthly PriceText$0.00
Trial Period MonthsText0
Trial Period PriceText$0.00
Trial Period TextText7-days
Trial Period Weekly PriceText$1.00
Trial Period WeeksText1
Trial Period Yearly PriceText$0.00
Trial Period YearsText0
Weekly PriceText$1.83
Yearly PriceText$100.00

The values above apply to any referenced product. There is the notion of a primary, secondary, tertiary and selected product. Whichever you use, you can use any of the above variables with it.

For example, to reference the price of the selected product (i.e. one the user has clicked or tapped on within the paywall) — you could write The selected product cost {{ products.selected.price }}.

For annual iOS App Store products with a monthly billing plan, each product also exposes billing plan variables:

VariableValuesUse it for
billingPlanTypeMONTHLY, UP_FRONT, or emptyShowing which plan the product will use when Apple can honor it.
isBillingPlanAvailabletrue or falseHiding monthly-installment copy when the selected billing plan is unavailable on the user's device or storefront.

For example, use products.selected.isBillingPlanAvailable with dynamic values before showing copy such as "Billed monthly for 12 months."

There are also stock variables that deal with products, but aren't part of a single product variable itself. They are referenced via the products variable:

PropertyTypeExample
Has Introductory OfferBoolTrue/False
Selected IndexNumber0

Use products.hasIntroductoryOffer to detect whether or not a user has a trial available. Further, products.selectedIndex represents the index of a selected product (i.e. primary would equal 0).

Superwall also exposes products.abandoned after a user cancels the store purchase sheet, and products.purchased after a transaction completes. Once those states are set, these variables point at the product the user abandoned or purchased, so you can use the same fields shown above:

PropertyTypeExample
Abandoned Product PriceText{{ products.abandoned.price }}
Abandoned Product PeriodText{{ products.abandoned.periodly }}
Purchased Product PriceText{{ products.purchased.price }}
Purchased Product PeriodText{{ products.purchased.periodly }}
PropertyTypeExample
Did Abandon TransactionBool{{ state.didAbandonTransaction }}
Did Complete TransactionBool{{ state.didCompleteTransaction }}

Use state.didAbandonTransaction to react when a user opens the App Store or Google Play purchase sheet and then cancels before purchase. A common pattern is to bind a drawer's open state to this variable so a recovery offer appears inside the same paywall. See Abandoned Transaction Paywalls for a full example.

PropertyTypeExample
Alias IdText$SuperwallAlias
Application Installed At IdText2024-04-15T04:59
.163Z
Event NameTextcustom_value
SeedNumber0

Use any variable above by referencing the user variable first: {{ user.seed }}.

Custom Variables

To create your own variable, click + Add Variable in the sidebar under the Variables section:

The variable editor will be presented:

You'll be presented with four fields to fill out:

  1. Type: The type of variable to create. Choose State if you'd like the variable to be mutated by tap behaviors. Parameter variables are similar, but initial values can be passed in from your app.
  2. Name: How you will reference the variable. Any name will autocorrect to camel case, i.e. "Cool Variable" will be coolVariable.
  3. Value Type: The variable type. Choose from text, number, or boolean.
  4. Initial Value: The initial value of the variable. This only displays once a variable type has been chosen.

Once you have everything entered, click Save. Your variable will show up in a section in the sidebar under Variables called Params:

From there, they are able to be referenced the same way as any other variable:

Liquid syntax formatting

In text, you can use Liquid filters to modify output. To use filters, add a pipe after the variable. Then, add in one or more filters:

// Results in 17, the absolute value of -17
{{ -17 | abs }}

For example, to capitalize a text variable, you would write:

// If the name was "jordan", this results in "JORDAN"
{{ user.name | upcase }}

Custom Liquid filters

Superwall adds filters to Liquid for dates and countdowns: date_add, date_subtract, countdown_from and localize_countdown. See Custom Liquid filters for each one, and Countdown Timers on Paywalls to build a timer.

Snippets with variables

If you create a group of components built off of variables and conditions, save it as a snippet to reuse. There are several stock snippets built this way. For example the Product Selector snippet:

Adding this snippet shows your products in a vertical stack:

When one is selected, the checkmark next to it is filled in. This is achieved with stock variables (i.e. the selected product) and then changing layer opacity based on if the checkmark's corresponding product is selected or not:

Testing and handling different states

Often times, you'll want to test things like introductory or trial offers, a certain page within a paging design, or keep a modal drawer open to tweak its contents or look. To do that, simply change the variable's value in the editor. On the left sidebar, click Variables and then search for the one you're after and set its value.

Here are some common examples:

  1. Testing introductory offers: To test trial or introductory offer states, change the products.hasIntroductoryOffer to true or false. In the example below, the text on the paywall changes based on whether or not a trial is available. To easily test it, you can toggle products.hasIntroductoryOffer:


  1. Testing abandoned transaction states: To test a drawer or offer that appears after a canceled purchase, change state.didAbandonTransaction to true. If your copy references the abandoned product, choose a product by setting products.abandonedProductId to its product reference, such as primary or secondary.

  2. Testing a particular page in a paging paywall: In this design, there are three distinct pages:


By default, the first one is showing. Though, if you needed to easily edit the second or third page, start by finding the variable that is controlling which page is shown. Typically, it'll be a state variable. Here, it's changeScreen:


By changing it, you can easily pull up each individual page and edit it as needed:


How is this guide?

On this page