Implement web paywalls

Before you begin, make sure you have configured your web paywall in the dashboard and installed Adapty SDK version 3.6.1 or later.

Open web paywalls

If you are working with a paywall you developed yourself, you need to handle web paywalls using the SDK method. The .openWebPaywall method:

Generates a unique URL allowing Adapty to link a specific paywall shown to a particular user to the web page they are redirected to.
Tracks when your users return to the app and then requests .getProfile at short intervals to determine whether the profile access rights have been updated.

This way, if the payment has been successful and access rights have been updated, the subscription activates in the app almost immediately.

import { adapty } from '@adapty/capacitor';

try {
  await adapty.openWebPaywall({ paywallOrProduct: product });
} catch (error) {
  console.error('Failed to open web paywall:', error);
}

There are two versions of the openWebPaywall method:

openWebPaywall({ paywallOrProduct: product }) that generates URLs by paywall and adds the product data to URLs as well.
openWebPaywall({ paywallOrProduct: paywall }) that generates URLs by paywall without adding the product data to URLs. Use it when your products in the Adapty paywall differ from those in the web paywall.

In SDK v4, the paywall side of paywallOrProduct takes an AdaptyFlowPaywall — a paywall variation of the fetched flow. Check that flow.paywalls isn’t empty before indexing into it, for example flow.paywalls[0].

Handle errors

Error	Description	Recommended action
AdaptyError.paywallWithoutPurchaseUrl	The paywall doesn’t have a web purchase URL configured	Check if the paywall has been properly configured in the Adapty Dashboard
AdaptyError.productWithoutPurchaseUrl	The product doesn’t have a web purchase URL	Verify the product configuration in the Adapty Dashboard
AdaptyError.failedOpeningWebPaywallUrl	Failed to open the URL in the browser	Check device settings or provide an alternative purchase method
AdaptyError.failedDecodingWebPaywallUrl	Failed to properly encode parameters in the URL	Verify URL parameters are valid and properly formatted

Get the web paywall URL without opening it

If you want to present the web purchase page yourself instead of letting the SDK open it, use createWebPaywallUrl. It returns the same unique URL that openWebPaywall would open, so you can render it in your own web view or handle the redirect on your terms. It accepts the same paywallOrProduct argument — a paywall variation of the fetched flow (AdaptyFlowPaywall) or an AdaptyPaywallProduct.

import { adapty } from '@adapty/capacitor';

try {
  const url = await adapty.createWebPaywallUrl({ paywallOrProduct: product });
  // open `url` in your own web view, or handle the redirect yourself
} catch (error) {
  console.error('Failed to create web paywall URL:', error);
}

To open an arbitrary URL (not a web paywall) through the native browser — for example, from a flow’s button — use adapty.openWebUrl instead.

Open web paywalls in an in-app browser

Opening web paywalls in an in-app browser is supported starting from Adapty SDK v3.15.

By default, web paywalls open in the external browser.

To provide a seamless user experience, you can open web paywalls in an in-app browser. This displays the web purchase page within your application, allowing users to complete transactions without switching apps.

To enable this, set openIn to WebPresentation.BrowserInApp in openWebPaywall:

import { adapty, WebPresentation } from '@adapty/capacitor';

try {
    await adapty.openWebPaywall({
        paywallOrProduct: product,
        openIn: WebPresentation.BrowserInApp, // default – WebPresentation.BrowserOutApp
    });
} catch (error) {
    console.error('Failed to open web paywall:', error);
}