REST API Reference

Complete reference for PaywallOS API endpoints.

For a step-by-step integration guide, see External Integration Guide.

Health Check

GET/api/openverb/health

Verify connectivity. No auth required.

{ "status": "ok", "message": "PaywallOS Service is active" }

Check Verb (Simple GET)

GET/api/openverb/check-verb

Query: appId, userId, verb, tier (optional, must be slug e.g. free/pro, not UUID). Returns { allowed, verb, tier, requiredTier?, message }.

Check Verb Access (POST)

POST/api/openverb/check

Description

Check if a user has access to perform a specific verb action.

Request Body

{
  "verbId": "export_data",
  "actor": { "type": "user", "id": "user_123" },
  "context": { "tenantId": "app_456", "planId": "pro" }
}

Response (allowed)

{
  "ok": true,
  "receipt": {
    "executionId": "...",
    "verbId": "export_data",
    "status": "ok",
    "actorId": "user_123",
    "tenantId": "app_456"
  }
}

Response (denied)

{
  "denied": true,
  "reason": {
    "code": "tier_required",
    "message": "Upgrade to Pro"
  },
  "upsell": {
    "suggestedPlanId": "pro",
    "cta": "Upgrade Now"
  }
}

Get Verb Library

GET/api/openverb/library

Description

Retrieve the complete OpenVerb library for your app.

Query Parameters

?appId=app_456

Response

{
  "namespace": "myapp.core",
  "version": "1.0.0",
  "verbs": [
    {
      "id": "verb_789",
      "name": "export_data",
      "category": "file_system",
      "description": "Export user data to CSV"
    }
  ]
}

Get User Tier

GET/api/openverb/user-tier

Description

Get the tier for a user in your app. Use userId as your app's external user ID. Returns the tier slug (e.g. free, pro) based on their subscription.

Query Parameters

?appId=app_456&userId=user_123

Response

{
  "tier": "pro"
}

End Users (Customers)

GET/api/end-users|POST/api/end-users

List or create end-users (customers) for your organization. Requires dashboard auth.organizationId is passed as a query param (GET) or in the body (POST).

POST Body

{
  "organizationId": "org_xxx",
  "externalUserId": "user_123",
  "email": "user@example.com",
  "metadata": { "name": "Display Name" }
}

Stripe Checkout

POST/api/stripe/checkout

Create a Stripe Checkout session. Use appId + API key (no organizationId needed).

Request (appId + API key)

POST /api/stripe/checkout
Authorization: Bearer <your_api_key>

{
  "appId": "your-app-uuid",
  "planId": "tier-uuid",
  "userId": "your-user-id",
  "successUrl": "https://yourapp.com/success",
  "cancelUrl": "https://yourapp.com/cancel"
}

Response

{ "sessionId": "cs_...", "url": "https://checkout.stripe.com/..." }

Redirect the user to url. Get tier IDs from the app page in the dashboard.

Billing Portal (Cancel / Manage)

POST/api/stripe/customer-portal

Get a Stripe Customer Portal URL so your end-users can cancel their subscription, update payment methods, or view invoices. Use appId + API key (no organizationId needed).

Request (appId + API key)

POST /api/stripe/customer-portal
Authorization: Bearer <your_api_key>

{
  "appId": "your-app-uuid",
  "userId": "your-user-id",
  "returnUrl": "https://yourapp.com/account"
}

Response

{ "url": "https://billing.stripe.com/..." }

Redirect the user to url. Stripe hosts the portal — users can cancel (at end of period), update payment, view invoices. returnUrl is where they land after closing the portal.

Get User Entitlements

GET/api/openverb/entitlements

Description

Get all verbs a user is entitled to access based on their tier.

Query Parameters

?userId=user_123&appId=app_456

Response

{
  "userId": "user_123",
  "tier": "pro",
  "entitlements": [
    {
      "verbId": "export_data",
      "verbName": "export_data",
      "usageLimit": {
        "limit": 100,
        "used": 45,
        "period": "monthly"
      }
    }
  ]
}

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer pk_live_...

Rate Limits

Free tier:1,000 requests/month

Pro tier:100,000 requests/month

Enterprise tier:Unlimited

Client SDK

Copy lib/paywall-sdk.ts from the PaywallOS repo. It provides initPaywallOS and usePaywallOS:

import { initPaywallOS, usePaywallOS } from '@/lib/paywall-sdk'

// One-time init (scans DOM for verb= attributes)
initPaywallOS(apiKey, appId, userId, userTier)

// Or use the hook for programmatic checks
const { checkVerb } = usePaywallOS(apiKey, appId, userId, userTier)
const response = await checkVerb('export_data')
if (response.ok) { /* allowed */ }
else if (response.denied) { /* response.reason?.message */ }

Need help?

Check out our examples or contact support for assistance.