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:
Intercepts 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