Paywall Customization

Overview

The paywall system controls access to your content based on reader behavior, subscription status, and geographic location. You can configure different rules for different products (websites or applications) and customize access policies per country.

Accessing Paywall Configuration

Navigate to Administration → Revenue Configuration → Paywall tab to manage your paywall rulesets.

Understanding Paywall Rulesets

A ruleset defines how content access is controlled for a specific product. Each ruleset contains:

• Display Name: A human-readable name for this ruleset
• Product Name: An alphanumeric identifier used by your API to reference this ruleset
• Country Rules: Specific access policies for different countries

Creating a New Ruleset

1. Click Add new ruleset from the Paywall index page
2. Enter a Display Name (e.g., “Main Website Paywall”)
3. Enter a Product Name (e.g., “mainsite”) - this identifier will be used in your API calls
4. Configure country-specific rules (see below)
5. Click Create ruleset

Configuring Country Rules

Each ruleset must have a World rule that serves as the default for all countries. You can then add specific rules for individual countries to override the default behavior.

Rule Parameters

Paywall Limit

The number of free articles a reader can access before hitting the paywall.

• Set to 0 for unlimited free access
• Example: 5 means readers can view 5 articles before being prompted to subscribe
• This limit is tracked per reader across a 30-day rolling window

Datawall Limit

The number of articles a reader can access before being required to log in (even if they’re not subscribing).

• Set to 0 to disable the datawall
• Example: 2 means anonymous readers must create a free account after 2 articles
• This helps you capture reader data while still offering free content

Important: The datawall limit should typically be lower than the paywall limit. For instance:

• Datawall: 2 - reader must log in after 2 articles
• Paywall: 5 - logged-in reader must subscribe after 5 total articles

Premium Access

Controls how premium/paid content is handled for readers in this country:

• Default (require subscription): Standard behavior - premium content requires an active subscription
• Allow (free access to premium): Premium content is accessible for free in this country (useful for sponsored regions or promotional markets)
• Deny (block access): Premium content is completely blocked for this country (useful for licensing restrictions)

The World Rule

The World rule is mandatory and cannot be removed. It acts as the default configuration for any country that doesn’t have a specific rule defined.

Example Configuration:

World (Default):
- Paywall Limit: 5
- Datawall Limit: 2
- Premium Access: Default

This means readers worldwide get 2 free articles anonymously, then must log in to read 3 more, then must subscribe for unlimited access.

Adding Country-Specific Rules

1. In the ruleset editor, click Add country rule
2. Select a country from the dropdown
3. Configure the limits and premium access policy
4. Click Update ruleset to save

You can add as many country-specific rules as needed. Each country can only appear once per ruleset.

Example: You might offer more generous limits in your home market:

United States:
- Paywall Limit: 10
- Datawall Limit: 5
- Premium Access: Default

Netherlands:
- Paywall Limit: 0 (unlimited)
- Datawall Limit: 3
- Premium Access: Allow (free premium access)

Removing Country Rules

To remove a country-specific rule, click the Remove this country button at the bottom of that rule’s section. The World rule cannot be removed.

Premium Content

Content can be marked as Premium in its metadata during content creation. Premium content has additional access restrictions:

• Non-premium content: Subject to the paywall and datawall limits configured in your rules
• Premium content: Always requires a valid subscription (unless the country’s Premium Access is set to “Allow”)

Readers who are subscribed to the appropriate subscription group(s) can access premium content immediately, regardless of paywall limits.

How It Works

When a reader requests content:

1. System checks if content is premium

   • If premium and reader is subscribed → Grant access
   • If premium and country rule is “Allow” → Grant access
   • If premium and not subscribed → Require subscription

2. For non-premium content, system checks limits

   • If reader hasn’t hit datawall limit → Grant access
   • If reader is logged in but hasn’t hit paywall limit → Grant access
   • If limits exceeded → Prompt to subscribe

Product Integration

Each product (website, mobile app, etc.) should:

1. Send the Product Name identifier with API requests
2. Use the API to validate reader access to content
3. Implement the appropriate prompts (login, subscribe) based on API responses

API Implementation

Use the Paywall API endpoints to integrate your ruleset with your applications:

📘 Paywall API Documentation

The API will:

• Evaluate reader access based on your configured rules
• Track article consumption against limits
• Return whether access should be granted and what action (if any) is required
• Handle country detection automatically via IP geolocation or Cloudflare headers

Best Practices

Recommended Configurations

Standard News Site:

Paywall Limit: 5
Datawall Limit: 2
Premium Access: Default

Freemium Model:

Paywall Limit: 10
Datawall Limit: 3
Premium Access: Default

Lead Generation Focus:

Paywall Limit: 15
Datawall Limit: 1
Premium Access: Default

Subscriber-Only:

Paywall Limit: 0
Datawall Limit: 0
Premium Access: Default
(Mark all content as Premium)

Tips

• Start generous: It’s easier to tighten limits later than to loosen them after reader complaints
• Test your flow: Create test rulesets and validate the reader experience before going live
• Monitor metrics: Track conversion rates at different limit thresholds to optimize
• Consider mobile: Mobile readers may have different tolerance for paywalls
• Geographic strategy: Adjust limits based on market maturity and competitive landscape

Troubleshooting

Readers reporting they hit the paywall too quickly

• Check that the correct ruleset is being passed in API calls
• Verify the product name matches exactly (case-sensitive)
• Ensure limits are configured as intended

Premium content accessible when it shouldn’t be

• Verify the Premium Access setting for the relevant country
• Check that content is correctly marked as Premium in metadata
• Ensure subscription groups are properly configured

Different limits for different content types

• The paywall system tracks total article consumption, not by content type
• Consider using multiple products (rulesets) for different content verticals
• Alternatively, mark premium tiers entirely as Premium content

Example Scenarios

Scenario 1: National News Site

Main Site Ruleset:

• World: Paywall 5, Datawall 2
• Home Country: Paywall 10, Datawall 3 (more generous for local readers)

Result: Local readers get more free articles, encouraging engagement in your primary market.

Scenario 2: Global Media Company

Mainstream Product:

• World: Paywall 5, Datawall 2, Premium: Default
• US/UK/CA: Paywall 8, Datawall 3, Premium: Default

Investigative Product:

• All content marked as Premium
• World: Paywall 2, Datawall 1, Premium: Default (for free preview content)

Result: Differentiated product tiers with investigative journalism behind a stricter paywall.

Scenario 3: Regional Publisher with Licensing Issues

Standard Ruleset:

• World: Paywall 10, Datawall 3
• Licensed Regions (US, CA): Paywall 10, Premium: Default
• Unlicensed Regions (CN, RU): Paywall 5, Premium: Deny

Result: Premium content with licensing restrictions is blocked in certain markets while free content remains available.

---

For technical implementation details and API reference, consult the Paywall API Documentation.