Creating Paywalls
How to create a new Paywall
Paywalls are currently supported for apps distributed in the Apple, Google and Amazon app stores. To create a new Paywall, follow these steps:
Select an Offering
First, click on Paywalls in the Products and pricing section of the Project you’re working on.
Then, click + Add paywall next to the Offering that you want to create a Paywall for.
If you’re looking to experiment with a new paywall, consider duplicating your default Offering and attaching your new paywall to the duplicated Offering. Duplicating an Offering with a paywall attached will also duplicate the paywall.
Select a template
The first thing to do when creating a new Paywall is to select the template you’ll use as the starting point. Templates may support different package setups, content layouts, image sizes, and much more; so we recommend browsing each template to pick the one that’s best suited for what you’re looking to accomplish with your paywall.
For example, if you’re trying to draw contrast between a few different packages you’re offering, try the #2 - Sphynx template. Or, if you want to try your own version of the Blinkist Free Trial Paywall start with the #3 - Leopard template.
If you need to showcase multiple packages, consider using the following templates:
- Template 2 - Sphynx Content
- Template 4 - Persian Content
- Template 5 - Bengal Content
If you are using the #7 - Siamese template, the minimum supported SDK versions of this Paywall are:
- iOS 5.2.0
- Android 8.3.0
- React Native 8.0.0
- Flutter 7.0.0
If you attempt to serve this Paywall on a lower SDK version we'll provide a fallback Paywall. Learn more.
How to configure your Paywall
Once you’ve selected a template, you can configure any of its properties on the right side of the screen and see the change previewed immediately.
Packages
Packages represent the individual products you want to serve a customer on your Paywall. You don’t necessarily need to display every package that’s available in your Offering, and some templates may only support displaying one or a limited number of packages, so be sure to choose a template that reflects the options you want to offer your customers.
The templates above that support multiple packages allow you to select a package name which will be displayed when this package is being shown. Below is a small explanation of each option that you can choose from:
- Subscription duration in months - The duration in months of the package selected (I.E. 12 months for Annual, 6 months, 1 month, etc...)
- Offer Period (Monthly, Annual, Etc...) - The name of the period selected when configuring the package in RevenueCat. So in this case, if you selected "Monthly" as your option when creating the package and putting the products into the package, then Monthly would be displayed as the package name in your paywall. If you choose Custom when configuring the package, the product identifier will show instead.
- Product Name - The name of the product configured in RevenueCat.
For templates that support multiple packages, you should select packages in the order that you’d like them to display. Then, you can separately choose which package should be preselected for your customers by default.
To test the impact of that choice, you can duplicate your Offering, preselect a different package, and run an Experiment between the two Offerings to see how it influences customer behavior on your Paywall.
Paywalls are only compatible with packages associated with subscription or non-consumable products like "lifetime" purchases.
Strings
How you describe your product has a huge impact on how likely a customer is to subscribe to it. Every descriptive string on our Paywall templates is fully configurable so you have control over exactly how you pitch your product.
Try using markdown formatting in any string property to add custom styling to your Paywall.
- Bold with
**this** - Italic with
*this*or_this_ - Strikethrough with
~this~ - Monospace with
`this` - Link with
[click here](https://revenuecat.com)
Variables
For some Paywall strings you may want to set values based on the package that’s being displayed instead of hardcoding a single value, such as when quoting a price, or describing the duration of an Introductory Offer.
To make this easier and ensure accuracy, we recommend using Variables for these values that are package-specific.
For example, to show a CTA like “Try 7 Days Free & Subscribe”, you should instead use the {{ sub_offer_duration }} variable, and enter “Try {{ sub_offer_duration }} Free & Subscribe” to ensure the string is accurate for any product you use, even if you make changes to the nature of the offer in the future.
We support the following variables:
| Variable | Description | Example Value | iOS SDK | Android SDK |
|---|---|---|---|---|
| product_name | The name of the product from the store (e.g. product localized title from StoreKit) for a given package | CatGPT | * | * |
| price | The localized price of a given package | $39.99 | * | * |
| price_per_period | The localized price of a given package with its period length if applicable | $39.99/yr | * | * |
| price_per_period_full | The localized price of a given package with its period length unabbreviated if applicable | $39.99/year | 4.35.0 | 7.5.0 |
| total_price_and_per_month | The localized price of a given package with its monthly equivalent price if it has one | $39.99/yr ($3.33/mo) | * | * |
| total_price_and_per_month_full | The localized price of a given package with its monthly equivalent price if it has one | $39.99/year ($3.33/month) | 4.35.0 | 7.5.0 |
| sub_price_per_month | The localized price of a given package converted to a monthly equivalent price | $3.33 | * | * |
| sub_price_per_week | The localized price of a given package converted to a weekly equivalent price | $3.33 | 4.30.0 | 7.2.0 |
| sub_duration | The duration of the subscription; '1 month', '3 months', '1 year', etc. | 1 year | * | * |
| sub_duration_in_months | The duration of the subscription in months; '3 months', '12 months', etc. | 12 months | * | * |
| sub_period | The length of each period of the standard offer on a given package | Monthly | * | * |
| sub_period_length | The unabbreviated length of each period of the standard offer on a given package | month | 4.35.0 | 7.5.0 |
| sub_period_abbreviated | The abbreviated length of each period of the standard offer on a given package | mo | 4.35.0 | 7.5.0 |
| sub_offer_duration | The period of the introductory offer on a given package | 7 days | * | * |
| sub_offer_duration_2 | The period of the second introductory offer on a given package (Google Play only) | 7 days | * | * |
| sub_offer_price | The localized price of the introductory offer of a given package | $4.99 | * | * |
| sub_offer_price_2 | The localized price of the second introductory offer of a given package (Google Play only) | $4.99 | * | * |
| sub_relative_discount | The localized discount percentage compared to the most expensive package per period | 19% off | 4.26.0 | 7.2.0 |
Some variables are not available on all version of the SDK. If an unavailable variable is found on an older version of the SDK, RevenueCatUI will automatically display a default paywall to avoid showing a broken paywall. To prevent this, you may use Targeting to control who can see a paywall with a newer variable.
Previewing Paywalls
Click the Show preview values checkbox to see your Paywall with example preview values instead of the raw variables.
The paywall preview is generated using our example data. Please note that you may observe placeholder values from the example values in the table above, such as product names or prices in the preview of your newly created paywall. To obtain a more accurate preview, we recommend running your application on your physical device or in the simulator, as this will present details more closely aligned with your actual product information.
Intro offer eligibility
RevenueCat Paywalls automatically check for Introductory Offer eligibility, and therefore for applicable fields like the Call to action and Offer details you can enter distinct strings based on the nature of the offer. For example, you may want to highlight the length of your free trial for a customer who is eligible for that Introductory Offer.
Uploading images
Use the Select a file button for the applicable image to upload your own to use for your Paywall. We support .jpg, jpeg, and .png files up to 5MB. We’ll center and scale the image to fit regardless of their size, but we recommend using images of the following aspect ratios on each template:
| Template | Recommended aspect ratio |
|---|---|
| Template 1 - Jaguar | 6:5 |
| Template 2 - Sphynx (Icon) | 1:1 |
| Template 2 - Sphynx (Bg) | 19.5:9 |
| Template 3 - Leopard | 1:1 |
| Template 4 - Persian | 19.5:9 |
| Template 5 - Bengal | 2:1 |
| Template 7 - Siamese | 2:1 |
Colors
Use your own hex codes, select a custom color, or use our color picker to select background and text colors for each element that reflect your app’s branding.
The color picker can be used outside of your browser window as well if you need to grab colors from assets in other applications.
Localization
RevenueCat Paywalls come with built-in support for localization. This will allow you to customize your paywall content for all the languages that your app supports.
Locales can be added to your paywall through the 'Localization' dropdown.
Each paywall template may differ in the localized values that you will need to provide. The options that most templates have are:
- Title
- Subtitle
- Package details
- Package details for an introductory offer
- Call to action
- Call to action for an introductory offer
Since RevenueCatUI allows for dynamic text with Variables, all the output of variables will automatically localized. This includes period lengths like "Annual", "Monthly" and "Weekly" being localized to "Anual", "Mensual", and "Semanalmente". Price per period like "$6.99/mo" and "$53.99/yr" will also be localized to "$6.99/m." and "$53.99/año".
Other paywall components like "Restore purchases", "Terms of Service", and "Privacy Policy" will also automatically be localized.
Supported locales
We currently support all 39 locales that are supported on App Store Connect.
- Arabic (Saudi Arabia) -
ar - Catalan -
ca - Chinese (Simplified) -
zh - Chinese (Traditional) -
zh - Croatian -
hr - Czech -
cs - Danish -
da - Dutch (Netherlands) -
nl - English (Australia) -
en - English (Canada) -
en - English (United Kingdom) -
en - English (United States) -
en - Finnish -
fi - French (Canada) -
fr - French (France) -
fr - German (Germany) -
de - Greek -
el - Hebrew -
he - Hindi -
hi - Hungarian -
hu - Indonesian -
id - Italian -
it - Japanese -
ja - Korean -
ko - Malay -
ms - Norwegian -
no - Polish -
pl - Portuguese (Brazil) -
pt - Portuguese (Portugal) -
pt - Romanian -
ro - Russian -
ru - Slovak -
sk - Spanish (Mexico) -
es - Spanish (Spain) -
es - Swedish -
sv - Thai -
th - Turkish -
tr - Ukrainian -
uk - Vietnamese -
vi
If a particular translation is not applied to your Paywall during testing, you may need to change the default localization in Xcode to that language.
Default Localization
As of the following SDK versions, we support setting a Default Localization when creating or editing a Paywall. The Default Localization will be served to your customers when their preferred localization is not available.
| RevenueCat SDK | Version required for Default Localization setting |
|---|---|
| purchases-ios | 5.3.0 and up |
| purchases-android | 8.6.0 and up |
| react-native-purchases-ui | 8.1.0 and up |
| purchases-flutter | 8.1.0 and up |
Getting your paywall approved by the stores
Paywalls are frequently one of the most scrutinized areas of your app in App Store and Play Store review, since the stores want to ensure apps are setting clear expectations about what’s being offered to customers. Below are some of the most common rejection reasons, and how you can best position yourself to avoid them with RevenueCat Paywalls:
Full billed amount is not clearly shown Though it can be useful to show the relative value of one option over another by comparing the two with a common duration (e.g. normalizing your $49.99/yr subscription to the equivalent of $4.16/mo), it’s important that the full billed amount ($49.99/yr) is clearly provided on your paywall.
You can provide this using variables like price_per_period / price_per_period_full depending on your preferred format, or total_price_and_per_month / total_price_and_per_month_full if you still want to show the monthly equivalent price of your package if applicable.
However, other variables like sub_price_per_month or price on their own may not satisfy this requirement unless your paywall clearly states the full billed amount in some other way.
Introductory offer is not clearly shown Similar to the full billed amount, if the nature of the introductory offer is not clear enough on your paywall, your app may also get rejected for that reason, since this is what the customer is about to receive (and potentially pay for) immediately upon converting.
To address this with RevenueCat Paywalls, consider using sub_offer_price and sub_offer_duration in either your package details or your CTA to ensure that the introductory offer is clearly disclosed.
India has particularly strict rules regarding the disclosure of offer terms, and you may find that your paywall is more likely to get rejected for that reason if its offered in India.
The opportunity to cancel is not clearly disclosed In addition, in some cases the store will look for explicit language around the fact that customers can cancel their subscription, as well as how they might do that; so considering adding these notes if you want to be sure to avoid a rejection for that reason. (e.g. "Try free for x days, then $y/mo. Cancel anytime.")
Missing terms & conditions or missing privacy policy Though the App Store in particular no longer requires these policies to be accessible directly from your paywall, they do still require that they are accessible somewhere in your app, and the paywall is a common place for them to be.
If either the terms & conditions or the privacy policy of your app is missing, or just too difficult to find in the reviewer's opinion, your app may be rejected for that. To prevent this, try providing the terms & privacy policy on your paywall through RevenueCat Paywalls so they'll be easy for your customers and for app reviewers to find.