sesamy-paywall

A web component that displays a paywall for content, loading paywall settings from a remote URL and supporting different templates (Article, Boxes, Login).

Props/Attributes

• settings-url - (Optional) URL to fetch paywall settings. When absent, the component falls back to the paywall URL resolved from your vendor client configuration's content selectors (the paywall-url attribute on the article element). Most CMS integrations rely on this fallback. A ?lab_opts query parameter on the page flips the priority for preview flows. With neither source, the component renders nothing
• item-src - URL of the content item
• price - Price of the content
• currency - Currency code for the price
• redirect-url - URL to redirect after purchase
• utm-source, utm-medium, utm-campaign, utm-term, utm-content - UTM parameters for tracking
• pass - Pass ID for access

Events

The paywall emits two kinds of events: events on the sesamy-js event bus, and DOM CustomEvents on the element itself.

SDK bus events

Listen with window.sesamy.events.on(...):

• sesamyPaywallAccessChecked - Emitted after access check, with { hasAccess, paywallId, articleUrl, passes } in detail
• sesamyPaywallCreateCheckout - Emitted before checkout creation, with the full checkout payload and the selected product. The event is cancellable: cancel it to intercept or replace the purchase flow
• sesamyPaywallProductSelected - Emitted after the checkout has been created successfully, with { product, checkoutId, paywallId } in detail. If checkout creation fails, the event never fires
• sesamyPaywallCheckoutRedirect - Emitted before redirecting to checkout, with { checkoutId, country, paymentMethod } in detail. The event is cancellable: cancel it to skip the redirect
• sesamyPaywallResetCheckout - Emitted when the user backs out of an in-progress checkout

window.sesamy.events.on('sesamyPaywallCreateCheckout', (event) => {
  console.log('Checkout about to be created for', event.detail.product);
});

DOM events

Dispatched on the element as bubbling, composed CustomEvents, so you can listen on the element or any ancestor:

• sesamy:paywall-shown - Dispatched when the paywall is shown, with detail.reason (for example 'unauthenticated' or 'no-entitlement')
• sesamy:paywall-dismissed - Dispatched when the component is removed after the paywall was shown but the user did not convert
• sesamy:access-granted - Dispatched when the user has access, with detail.scopes

document.querySelector('sesamy-paywall').addEventListener('sesamy:paywall-shown', (event) => {
  console.log('Paywall shown because', event.detail.reason);
});

Basic Usage

<!-- Article paywall -->
<sesamy-paywall
  settings-url="https://api.sesamy.com/paywall/paywalls/acme/pw_abc123.json"
  item-src="https://acme.com/article"
  price="99"
  currency="USD"
>
  <div slot="features">✔️ Unlimited access<br />✔️ Cancel anytime</div>
</sesamy-paywall>

<!-- Login paywall with below-headline slot -->
<sesamy-paywall settings-url="https://api.sesamy.com/paywall/paywalls/acme/pw_login123.json">
  <div slot="below-headline">Additional content below headline</div>
</sesamy-paywall>

Slots

The sesamy-paywall component provides two main slots for customization:

below-headline

• Purpose: Inserts custom content directly below the paywall headline
• Behavior: The content you provide in this slot will be rendered in addition to the default paywall content, immediately below the headline. Use this for adding extra information, banners, or custom elements. Works on all templates

<sesamy-paywall settings-url="https://api.sesamy.com/paywall/paywalls/acme/pw_login123.json">
  <div slot="below-headline">Special offer for new readers</div>
</sesamy-paywall>

features

• Purpose: Replaces the default features section of the paywall
• Behavior: When you provide content in the features slot, it will completely replace the built-in features list or section. Use this slot to fully customise the list of benefits, features, or selling points shown to the user. The slot only renders in the Article template, and only once a product is selected. In the Boxes template each box renders its own features from the paywall settings, and the slot is not projected

<sesamy-paywall settings-url="https://api.sesamy.com/paywall/paywalls/acme/pw_abc123.json">
  <div slot="features">
    <ul>
      <li>✔️ Unlimited access</li>
      <li>✔️ Cancel anytime</li>
      <li>✔️ Exclusive articles</li>
    </ul>
  </div>
</sesamy-paywall>

Adding versus replacing

The below-headline slot adds to the paywall and works on all templates. The features slot replaces the default features section entirely and only applies to the Article template.

Paywall Templates

The component supports different paywall templates that can be configured via the settings-url:

• Article - Designed for single article purchases
• Boxes - Product selection with multiple options. Renders one column on narrow containers and at most three boxes per row on wide ones; exactly four subscriptions render as a two-by-two grid at every width
• Login - Simple login gate for registered users

Design Tokens

See Styling Components for the styling model and the global tokens.

Token	Styles	Default
--sesamy-paywall-primary-color	Paywall accent	mainColor from paywall settings
--sesamy-paywall-bg-color	Paywall background	settings background, else #FFFFFF
--sesamy-paywall-text-color	Paywall text	auto black/white by background contrast
--sesamy-paywall-border-radius	Corner radius (mobile)	8px
--sesamy-paywall-border-radius-desktop	Corner radius on wide containers	3x border-radius
--sesamy-paywall-theme	Set dark or light to force the theme	auto
--sesamy-paywall-btn-bg-color	Purchase button background	paywall accent
--sesamy-paywall-btn-text-color	Purchase button text	auto by contrast
--sesamy-paywall-tag-bg-color	Campaign tag background	paywall accent
--sesamy-paywall-tag-text-color	Campaign tag text	auto by contrast

Forcing the theme

--sesamy-paywall-theme is functional, not just cosmetic. By default the paywall picks a dark or light theme automatically based on background contrast; setting the token to dark or light overrides that choice.