RevenueCat Billing and Web SDK

⚠️Beta Feature

RevenueCat Billing and the RevenueCat Web SDK are currently in beta.

Introduction

RevenueCat Billing and the Web SDK allow you to easily offer web subscriptions. It utilizes Stripe as the payment gateway. This means you will need to set up and connect your Stripe account to RevenueCat.

RevenueCat Billing differs from our Stripe Billing / Stripe Checkout integration in that it takes care of the purchase UI, the subscription management portal, and the recurring billing logic. Stripe will still charge a payment processing fee if you use RevenueCat Billing, but you will not have to pay Stripe Billing / Checkout fees.

Installation

Start by installing the @revenuecat/purchases-js package using the package manager of your choice:

npm

npm install --save @revenuecat/purchases-js

yarn

yarn add @revenuecat/purchases-js

📘

When testing RevenueCat Billing with unpkg, add Purchases before all method names to access them. For example, use Purchases.Purchases.configure() instead of Purchases.configure().

General setup

Connect with Stripe

To get started, you first need to connect your Stripe account with RevenueCat, if you haven't already done so.

App configuration

To start using RevenueCat Billing, you will need to add a RevenueCat Billing App to your project. To do that, go the project settings, and in the "Apps" section, click "New", then "RevenueCat Billing":

In the following step, you can set up the most important information for the new App:

• App Name: The name of the app. This will also be shown in the purchase flow, in emails, and on invoices.
• Stripe Account: The Stripe account to use. To use a different Stripe account not shown in the list, connect it to RevenueCat first.
• Default Currency: The default currency to use for the prices of the products. Read more about multi-currency support in RevenueCat Billing.
• Seller Company Name: The name of your company. This will also be shown in the purchase flow, in emails, and on invoices.
• Appearance: Allows customizing the colors of the purchase flow. Read more about customizing the appearance.
• Support Email: An email address that customers can send support requests to. This will also be shown in the purchase flow, in emails, and on invoices.

After creating the app, some additional fields will be shown:

• App icon: You can upload an app icon here that will be shown in the purchase flow, in emails, and on invoices.
• Public API Key: The API key to be used in your web application when initializing the SDK. This key is safe to be included in production code.
• Sandbox API Key: The API key to be used for testing purposes. Do not share this API key or include it in your production web app, as it allows to make purchases and unlocking entitlements using test cards.

Product configuration

To get started with the Web SDK, you should follow the regular setup of entitlements, products, and offerings.

In contrast to Apple App Store, Google Play Store, and Stripe Billing products, you can configure your product and its duration directly in the RevenueCat dashboard:

SDK configuration

Configure the RevenueCat Web SDK by calling the static configure() method of the Purchases class:

Web (JS/TS)

const appUserId = authentication.getAppUserId(); // Replace with your own authentication system
const purchases = Purchases.configure(REVENUECAT_BILLING_PUBLIC_API_KEY, appUserId);

⚠️Only configure once

You should configure the SDK only once in your code.

You can use the object returned from the configure() method to call any of the SDK methods, or use the static method getSharedInstance() of the Purchases class to returned the initialized Purchases object.

The method will throw an exception if the SDK has not yet been configured.

Identifying customers

In contrast to our mobile SDKs, the Web SDK currently supports only identified (non-anonymous) customers. There are two reasons for this limitation:

1. In contrast to mobile app stores, there is no "restore purchase" functionality linked to a store account of the customer. Therefore, an anonymous purchase might get lost if the customer reloads their browser or clears their cache/cookies.
2. It is not possible to write a secure web application completely without a backend, since it is easily possible for a malicious actor to manipulate the state of the application through the browser's developer tools. Therefore, any web app using RevenueCat Billing to manage subscriptions also needs a backend component to check for access, which requires a shared customer ID.

One way of achieving this is by setting up an authentication / login mechanism, for example, using a third party authentication provider like Firebase / Supabase or a library like auth.js. The added benefit of this is that using a shared authentication mechanism between web app and mobile apps allows customers to access their subscriptions they made on the web in the mobile app as well, without any additional configuration (other than adding the products to the correct entitlements).

Alternatively, you could also provide the App User ID to your web application through a URL parameter, eg. via emails sent to customers you have acquired in your mobile app or use our Web Paywall Links functionality.

Getting customer information

You can access the customer information using the getCustomerInfo() method of the Purchases object:

Web (JS/TS)

try {
  customerInfo = await Purchases.getSharedInstance().getCustomerInfo();
  // access latest customerInfo
} catch (e) {
  // Handle errors fetching customer info
} 

You can then use the entitlements property of the CustomerInfo object to check whether the customer has access to a specific entitlement:

Web (JS/TS)

if ("gold_entitlement" in customerInfo.entitlements.active) {
  // Grant user access to the entitlement "gold_entitlement"
  grantEntitlementAccess();
}

If your app has multiple entitlements, you might also want to check if the customer has any active entitlements:

Web (JS/TS)

if (Object.keys(customerInfo.entitlements.active).length > 0) {
  // User has access to some entitlement, grant entitlement access
  grantEntitlementAccess();
}

Building your paywall

Getting and displaying products

We recommend using Offerings to configure which products get presented to the customer. You can access the offerings for a given app user ID with the (asynchronous) method purchases.getOfferings(). The current offering for the customer is contained in the current property of the return value.

Web (JS/TS)

try {
  const offerings = await Purchases.getSharedInstance().getOfferings();
  if (
    offerings.current !== null &&
    offerings.current.availablePackages.length !== 0
  ) {
    // Display packages for sale
    displayPackages(offerings.current.availablePackages);
  }
} catch (e) {
  // Handle errors
}

If you want to support multiple currencies and manually specify the currency, you can pass the currency code to the getOfferings() method. If you do not specify the currency, RevenueCat will attempt to geolocate the customer and use the currency of the customer's country if it's available, or fall back to the default currency of the app.

Web (JS/TS)

try {
  // Specify the currency to get offerings for
  const offerings = await Purchases.getSharedInstance().getOfferings({currency: "EUR"});
  if (
    offerings.current !== null &&
    offerings.current.availablePackages.length !== 0
  ) {
    // Display packages for sale
    displayPackages(offerings.current.availablePackages);
  }
} catch (e) {
  // Handle errors
}

It's also possible to access other Offerings besides the Current Offering directly by its identifier.

Web (JS/TS)

try {
  const offerings = await Purchases.getSharedInstance().getOfferings();
  if (offerings.all["experiment_group"].availablePackages.length !== 0) {
    // Display packages for sale
    displayPackages(offerings.all["experiment_group"].availablePackages);
  }
} catch (e) {
  // Handle errors
}

Each Offering contains a list of Packages. Packages can be accessed in a few different ways:

1. via the .availablePackages property on an Offering.
2. via the duration convenience property on an Offering
3. via the .packagesById property of an Offering, keyed by the package identifier

Web (JS/TS)

const allPackages = offerings.all["experiment_group"].availablePackages;
// --
const monthlyPackage = offerings.all["experiment_group"].monthly;
// --
const customPackage = offerings.all["experiment_group"].packagesById["<package_id>"];

Each Package contains information about the product in the rcBillingProduct property:

Web (JS/TS)

// Accessing / displaying the monthly product
try {
  const offerings = await Purchases.getSharedInstance().getOfferings({currency: "USD"});
  if (offerings.current && offerings.current.monthly) {
    const product = offerings.current.monthly.rcBillingProduct;
    // Display the price and currency of the RC Billing Product
    displayProduct(product);
  }
} catch (e) {
  // Handle errors
}

Purchasing a package

To purchase a package, use the purchase() method of the Purchases object. It returns a Promise<{customerInfo: CustomerInfo}>. To handle errors, you should catch any exceptions that occur.

Web (JS/TS)

try {
  const { customerInfo } = await Purchases.getSharedInstance().purchase({
    rcPackage: pkg
  });
  if (Object.keys(customerInfo.entitlements.active).includes("pro")) {
    // Unlock that great "pro" content
  }
} catch (e) {
  if (e instanceof PurchasesError && e.errorCode == ErrorCode.UserCancelledError) {
    // User cancelled the purchase process, don't do anything
  } else {
    // Handle errors
  }
}

Testing

You can use Stripe's Test Mode to test your RevenueCat Billing integration.

⚠️Ensure proper sandbox testing

In contrast to mobile app stores, there is no intermediary between you and the customer, and no App Review before you start charging customers money. Therefore, you should make sure that you have properly tested your implementation in sandbox mode before shipping your web subscriptions.

If you use the RevenueCat Billing sandbox API key, Stripe's test mode will be used automatically, and you can use one of Stripe's test cards to make purchases.

Current limitations

RevenueCat Billing currently has a number of known limitations. Most notably:

• There is no support for sales tax or VAT calculation
• There is no support for discounts or other offers
• There is no support for our Paywall templates yet
• Apple Pay and Google Pay are not currently supported as payment methods