PaywallOSPaywallOS
How It Works

From Zero to Paywall in 5 Minutes

PaywallOS makes monetization simple. Define verbs, map to tiers, add attributes. Done.

1

Create Your App

Sign up for PaywallOS and create your first app. You'll get an API key and App ID instantly.

# Install OpenVerb SDK (used by PaywallOS)
npm install @openverb/sdk

# Or copy the PaywallOS client from our repo
# lib/paywall-sdk.ts - set baseUrl: 'https://paywallos.openverb.org'
2

Define Your Verbs

Create an OpenVerb library describing what users can do in your app. Use our AI assistant or write it yourself.

{
  "namespace": "myapp.core",
  "verbs": [
    {
      "name": "export_data",
      "category": "file_system",
      "description": "Export user data to CSV"
    },
    {
      "name": "generate_report",
      "category": "analysis",
      "description": "Generate analytics report"
    }
  ]
}
3

Create Pricing Tiers

Set up your pricing tiers (Free, Pro, Enterprise, etc.) and add your Stripe Price IDs.

Free
$0
  • • Basic features
  • • 10 exports/month
Popular
Pro
$29
  • • All features
  • • 100 exports/month
Enterprise
$299
  • • Unlimited everything
  • • Priority support
4

Map Verbs to Tiers

Assign which verbs are available in each tier. Set usage limits if needed.

export_dataPro & above
generate_reportPro & above
ai_suggestionsEnterprise only
5

Add to Your App

Initialize PaywallOS and add verb= attributes. That's it!

import { initPaywallOS } from './paywall-sdk'

// Call once at app startup
initPaywallOS(apiKey, appId, user.id, user.tier)

// Your app - add verb= to any element
<button verb="export_data">Export</button>
<button verb="generate_report">Reports</button>
✓

Done! 🎉

PaywallOS now automatically:

  • PaywallOSIntercepts clicks on elements with verb= attributes
  • Checks user's subscription tier
  • Allows or blocks action in <10ms
  • Shows upgrade modal when blocked

How It Works Under the Hood

User clicks <button verb="export_data">
         ↓
PaywallOS intercepts click (capture phase)
         ↓
POST /api/openverb/check
  {
    verbId: "export_data",
    userId: "user_123",
    appId: "app_456"
  }
         ↓
Database queries:
  1. Get user's subscription tier
  2. Check if verb enabled for tier
  3. Check usage limits (if any)
         ↓
Response (~10ms):
  { ok: true, receipt: {...} }  // allowed
  or
  { denied: true, reason: { message: "Upgrade to Pro" } }  // blocked
         ↓
If allowed: Original action proceeds
If blocked: Show upgrade modal

Ready to Get Started?

Build your first paywall in 5 minutes