Management Paywall API

Manage paywall configurations and settings for your vendor through the Management API.

Overview

The Management Paywall API allows you to:

• Retrieve paywall configurations
• Access paywall settings and customizations
• Manage subscription and single-purchase options
• View payment method settings

Base URL

https://api2.sesamy.com/management/paywalls

Authentication

All requests require a valid JWT token with management API permissions:

curl -X GET https://api2.sesamy.com/management/paywalls/pw_123 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Endpoints

Get Paywall by ID

Retrieve the complete paywall configuration and settings for a specific paywall.

Endpoint:

GET /management/paywalls/{paywallId}

Path Parameters:

Parameter	Type	Required	Description
paywallId	string	Yes	Unique identifier of the paywall (e.g., pw_123)

Response (200 OK):

{
  "currency": "USD",
  "version": 1,
  "vendorId": "vendor_123",
  "headline": "Premium Content Access",
  "logoUrl": "https://example.com/logo.png",
  "mainColor": "#FF0000",
  "features": ["Feature 1", "Feature 2", "Feature 3"],
  "showLoginButton": true,
  "settings": {
    "useDefaultLogo": true,
    "useDefaultCurrency": true,
    "useDefaultColor": true
  },
  "subscriptions": [
    {
      "id": "sub_123",
      "title": "Premium Monthly",
      "description": "Monthly access",
      "price": 9.99,
      "sku": "premium-monthly",
      "periodText": "Monthly",
      "poId": "po_123",
      "tag": "popular",
      "discountCode": "",
      "selected": true
    },
    {
      "id": "sub_456",
      "title": "Premium Yearly",
      "description": "Yearly access with discount",
      "price": 99.99,
      "sku": "premium-yearly",
      "periodText": "Yearly",
      "poId": "po_456",
      "tag": "best-value",
      "discountCode": "SAVE20",
      "selected": false
    }
  ],
  "singlePurchase": {
    "enabled": true,
    "title": "Buy Now",
    "description": "One-time purchase",
    "discountCode": ""
  },
  "footerPaymentMethods": ["visa", "mastercard", "amex"]
}

Response Schema:

Field	Type	Description
currency	string	Currency code (e.g., "USD", "EUR")
version	integer	Paywall version number
vendorId	string	Associated vendor ID
headline	string	Main headline displayed on paywall
logoUrl	string	URL to vendor logo
mainColor	string	Primary color in hex format
features	array	List of features/benefits highlighted
showLoginButton	boolean	Whether to display login button
settings	object	Paywall display settings
subscriptions	array	Available subscription options
singlePurchase	object	Single purchase configuration
footerPaymentMethods	array	Payment methods displayed in footer

Error Responses:

Status	Code	Description
401	unauthorized	Missing or invalid JWT token
403	forbidden	User lacks permission to access this paywall
404	not_found	Paywall with specified ID not found
500	internal_error	Server error

Cache Headers:

Paywall configurations are cached for 1 hour:

Cache-Control: private, max-age=3600
Vary: Authorization, Cache-Timestamp

Examples

cURL

# Get a specific paywall
curl -X GET https://api2.sesamy.com/management/paywalls/pw_abc123 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

JavaScript/TypeScript

import { SesamyClient } from '@sesamy/sdk';

const client = new SesamyClient({
  apiKey: process.env.SESAMY_API_KEY,
  environment: 'production',
});

// Get paywall configuration
const paywall = await client.management.paywalls.get('pw_abc123');

console.log('Paywall headline:', paywall.headline);
console.log('Subscriptions:', paywall.subscriptions);
console.log('Payment methods:', paywall.footerPaymentMethods);

Python

from sesamy import SesamyClient

client = SesamyClient(
    api_key=os.environ['SESAMY_API_KEY'],
    environment='production'
)

# Get paywall configuration
paywall = client.management.paywalls.get('pw_abc123')

print(f"Paywall headline: {paywall['headline']}")
print(f"Subscriptions: {paywall['subscriptions']}")
print(f"Payment methods: {paywall['footer_payment_methods']}")

Use Cases

Display Paywall Configuration

Retrieve paywall settings to display them in your application:

async function displayPaywall(paywallId: string) {
  const paywall = await client.management.paywalls.get(paywallId);

  return {
    headline: paywall.headline,
    features: paywall.features,
    subscriptions: paywall.subscriptions,
    color: paywall.mainColor,
    logo: paywall.logoUrl,
  };
}

Cache Paywall Settings

Use the built-in caching headers to improve performance:

// Client will automatically cache this for 1 hour
const paywall = await client.management.paywalls.get(paywallId);

Access Subscription Details

Get available subscription plans for your paywall:

const paywall = await client.management.paywalls.get(paywallId);

paywall.subscriptions.forEach((sub) => {
  console.log(`${sub.title} - ${sub.price} ${paywall.currency}`);
});

Rate Limiting

Management API requests are rate-limited. See Rate Limits for details.

See Also

• Management API Overview
• Client Paywall API
• Implementing Paywalls Guide