Leaky Paywall

How to give readers free access to a limited number of articles before requiring a subscription.

Overview

A leaky paywall (also called metered access) lets readers view a set number of articles within a time period before the paywall appears. This is a common strategy for converting casual readers into subscribers: they get enough value to want more.

How it works

Leaky access has two distinct phases, which keeps the counter accurate:

1. Checking availability is free. When a reader opens a premium article, sesamy-js checks whether they have a free read remaining. This check does not record anything, so loading a page (or checking access more than once) never uses up an allowance.
2. Reading records the read. When the content is actually unlocked, sesamy-js registers the read. That single call records the read against the allowance and returns a signed link granting access. Re-opening an article you have already read does not consume another read.

If the allowance is exhausted, the unlock is refused and the paywall is shown instead.

The counter and time period are configured per paywall in the Sesamy dashboard. Common configurations:

Configuration	Behaviour
3 articles per month	Reader can view three premium articles each calendar month
5 articles per week	Reader can view five premium articles each week
1 article per day	Reader gets one free article each day

Integration

Leaky paywall works with both Capsule and the <sesamy-content-container> lock modes. sesamy-js handles it automatically when a paywall is configured with metered access, so no special client-side code is needed.

Under the hood, two calls back the two phases described above:

• paywalls.checkAccess advertises availability without recording a read. It returns status: "allowed" with the remaining count when a free read is available, or status: "paywall" when the allowance is exhausted.
• paywalls.registerAccess records the read and returns a signed link. sesamy-js calls this when it unlocks the content.

If you consume the signed link on your own backend (for example, to render a gated article server-side), see Token Validation.

With sesamy-content-container

When using lock modes like proxy or encode, the access check runs as part of hasAccess, and the read is registered when the content is unlocked. If leaky paywall grants access, the content is unlocked as normal.

With Capsule

When using Capsule, the access check runs before the unlock step, so a reader with a free read remaining is not shown the paywall prematurely. Authenticated readers then unlock the encrypted content as normal.

Anonymous readers with Capsule

For anonymous readers, combine the leaky paywall with a login requirement, or use a <sesamy-content-container> lock mode, to guarantee the content unlocks. See Reader identification below.

Configuration

Leaky paywall is configured per paywall in the Sesamy dashboard:

1. Navigate to the paywall settings for your vendor
2. Enable metered access
3. Set the number of free articles and the time period
4. Save. The changes take effect immediately

The paywall must be referenced in your content via the settings-url attribute or the paywallUrl content configuration.

Reader identification

The leaky paywall counter is tied to the reader's identity:

• Authenticated readers: Tracked by their Sesamy user ID. The counter persists across devices.
• Anonymous readers: Tracked by browser session and IP. Clearing cookies resets the browser portion of the counter.

For the most reliable experience, combine the leaky paywall with a login requirement after the free allowance is exhausted.

Next Steps

• Paywall Strategies -- A/B test which paywall variant converts best
• Content Protection -- How content is locked and unlocked
• Authentication Options -- Ensure readers are identified for accurate metering