Interface PresentPaywallParams

Parameters for the Purchases.presentPaywall method.

interface PresentPaywallParams {
    brandingAppearanceOverride?: Partial<BrandingAppearance>;
    customerEmail?: string;
    customVariables?: CustomVariables;
    discountCode?: string;
    externalPurchaseTokenId?: string;
    hideBackButtons?: boolean;
    htmlTarget?: HTMLElement;
    listener?: PaywallListener;
    metadata?: PurchaseMetadata;
    offering?: Offering;
    onBack?: (closePaywall: () => void) => void;
    onDiscountCodeChanged?: (discountCode: null | string) => void;
    onNavigateToUrl?: (url: string) => void;
    onPurchaseError?: (error: Error) => void;
    onVisitCustomerCenter?: () => void;
    purchaseHtmlTarget?: HTMLElement;
    selectedLocale?: string;
    showDiscountCodeField?: boolean;
}

Properties

brandingAppearanceOverride? customerEmail? customVariables? discountCode? externalPurchaseTokenId? hideBackButtons? htmlTarget? listener? metadata? offering? onBack? onDiscountCodeChanged? onNavigateToUrl? onPurchaseError? onVisitCustomerCenter? purchaseHtmlTarget? selectedLocale? showDiscountCodeField?

Properties

Optional ReadonlybrandingAppearanceOverride

brandingAppearanceOverride?: Partial<BrandingAppearance>

Overrides the branding appearance for the purchase started from this paywall. Only the provided values are overridden. These values take precedence over the override passed to Purchases.configure().

For Stripe Checkout, this customizes the supported mobile wallet experience. The Stripe-hosted fallback opened through "Pay another way" remains light and cannot currently be customized.

Optional ReadonlycustomerEmail

customerEmail?: string

The email of the customer starting the purchase. If passed the checkout flow will not ask for it to the customer.

Optional ReadonlycustomVariables

customVariables?: CustomVariables

Custom variables to pass to the paywall at runtime, overriding defaults set in the RevenueCat dashboard.

Variables must be defined in the dashboard first. Reference them in paywall text using the custom. prefix (e.g. {{ custom.player_name }}).

Example

presentPaywall({
  customVariables: {
    player_name: CustomVariableValue.string('Ada'),
    level: CustomVariableValue.number(42),
    is_premium: CustomVariableValue.boolean(true),
  },
});

Optional Readonly ExperimentaldiscountCode

discountCode?: string

Initial discount code to apply to the checkout when one already exists outside of the paywall UI, for example in the hosting page's URL.

Optional ReadonlyexternalPurchaseTokenId

externalPurchaseTokenId?: string

The RevenueCat public identifier for an Apple external purchase token.

Optional ReadonlyhideBackButtons

hideBackButtons?: boolean

Whether to hide back buttons in the paywall. Defaults to false.

Optional ReadonlyhtmlTarget

htmlTarget?: HTMLElement

The target element where the paywall will be rendered. The paywall will create a full-screen overlay if null.

Optional Readonlylistener

listener?: PaywallListener

Optional listener for paywall purchase lifecycle events.

Optional Readonlymetadata

metadata?: PurchaseMetadata

The purchase metadata to be passed to the backend when a purchase is started from the paywall. Any information provided here will be propagated to the payment gateway and to the RC transaction as metadata.

Optional Readonlyoffering

offering?: Offering

The identifier of the offering to fetch the paywall for. Can be a string identifier or one of the predefined keywords.

Optional ReadonlyonBack

onBack?: (closePaywall: () => void) => void

Callback to be called when the paywall tries to navigate back.

Example:

onBack: (closePaywall) => {
  // You may want to keep the paywall open while showing a confirmation
  // modal or logging analytics, then close it if the user confirms.
  // If you want the back action to dismiss the paywall immediately,
  // call closePaywall() right away.
  closePaywall();
}

Optional Readonly ExperimentalonDiscountCodeChanged

onDiscountCodeChanged?: (discountCode: null | string) => void

Called when the applied discount code changes in the checkout shown from the paywall. This can be used to sync host state such as URL parameters.

Optional ReadonlyonNavigateToUrl

onNavigateToUrl?: (url: string) => void

Callback to be called when the paywall tries to navigate to an external URL.

Markdown text links keep their native browser navigation. Use this callback for side effects or to customize how button-driven URL actions are handled.

Optional ReadonlyonPurchaseError

onPurchaseError?: (error: Error) => void

Callback called when an error that won't close the paywall occurs. For example, a retryable error during the purchase process.

Deprecated

Use listener.onPurchaseError instead.

Optional ReadonlyonVisitCustomerCenter

onVisitCustomerCenter?: () => void

Callback to be called when the paywall tries to visit the customer center.

Optional ReadonlypurchaseHtmlTarget

purchaseHtmlTarget?: HTMLElement

The target element where the checkout flow will be rendered. The checkout flow will create a full-screen overlay if null.

Optional ReadonlyselectedLocale

selectedLocale?: string

The locale to use for the paywall and the checkout flow.

Optional Readonly ExperimentalshowDiscountCodeField

showDiscountCodeField?: boolean

If set to true, the Web Billing checkout shown from the paywall will display a discount input code field.

Settings

Member Visibility

On This Page

Properties