API Documentation

RESTful API for PaywallPro Integration

Version: 1.0 STABLE

Overview

The PaywallPro API is a RESTful service that enables you to integrate subscription management, feature access control, and usage tracking into your applications. This API handles authentication, subscriber lifecycle, payment webhooks, and real-time feature gating.

Base URL

https://api.paywallpro.com/v1

Common Patterns

  • Versioning: API version is specified in the URL path (/v1/)
  • Rate Limiting: 1000 requests per hour per API key
  • Pagination: Use ?page=1&limit=50 for list endpoints
  • Timestamps: All timestamps are in ISO 8601 format (UTC)
  • ID Format: UUIDs (e.g., sub_7f3a9b2c1d4e)

Authentication

Authentication Methods

PaywallPro uses JWT (JSON Web Tokens) for secure API access. Each website has a unique API key that can be exchanged for a time-limited access token.

Required Headers

Authorization: Bearer <JWT_TOKEN> X-Website-Key: your_website_api_key

Get Access Token

Exchange your API key for a JWT access token

POST /v1/auth/token
Request Body:
{ "api_key": "sk_live_abc123xyz789", "api_secret": "secret_def456uvw012" }
Response:
{ "access_token": "eyJhbGciOiJIUzI1NiIs...", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "rt_abc123xyz789" }

Refresh Access Token

Obtain a new access token using a refresh token

POST /v1/auth/refresh
Request Body:
{ "refresh_token": "rt_abc123xyz789" }

Subscriber Management

Endpoints

Method Endpoint Description
POST /v1/subscribers Create a new subscriber
GET /v1/subscribers/{id} Get subscriber details
GET /v1/subscribers/{id}/status Get subscription status
PATCH /v1/subscribers/{id} Update subscriber information
POST /v1/subscribers/{id}/trials Activate trial subscription

Create Subscriber

POST /v1/subscribers
Request Body:
{ "email": "user@example.com", "name": "John Doe", "package_id": "pkg_starter", "metadata": { "company": "Acme Corp", "phone": "+1-555-0123" } }
Response (201 Created):
{ "id": "sub_7f3a9b2c1d4e", "email": "user@example.com", "name": "John Doe", "package": { "id": "pkg_starter", "name": "Starter", "price": 29.00 }, "status": "active", "trial_ends_at": "2024-11-22T12:00:00Z", "created_at": "2024-11-08T12:00:00Z" }

Get Subscription Status

GET /v1/subscribers/{id}/status
Response:
{ "subscriber_id": "sub_7f3a9b2c1d4e", "status": "active", "package": "pkg_starter", "trial": false, "trial_ends_at": null, "current_period_start": "2024-11-01T00:00:00Z", "current_period_end": "2024-12-01T00:00:00Z", "cancel_at_period_end": false }

Feature Access Control

Feature access control allows you to check if a subscriber has access to specific features and enforce usage limits for metered features.

Check Feature Access

Verify if a subscriber can access a specific feature

POST /v1/access/check
Request Body:
{ "subscriber_id": "sub_7f3a9b2c1d4e", "feature_code": "api_access", "check_limits": true }
Response:
{ "has_access": true, "feature": { "code": "api_access", "name": "API Access", "type": "boolean" }, "limits": null, "reason": null }

Get Feature Limits

Retrieve current usage and limits for a subscriber

GET /v1/subscribers/{id}/limits
Response:
{ "subscriber_id": "sub_7f3a9b2c1d4e", "limits": [ { "feature_code": "api_calls", "limit": 10000, "used": 4523, "remaining": 5477, "reset_at": "2024-12-01T00:00:00Z" }, { "feature_code": "storage_gb", "limit": 100, "used": 67.5, "remaining": 32.5, "reset_at": null } ] }

Limit Exceeded Response

When a feature limit is reached

{ "has_access": false, "feature": { "code": "api_calls", "name": "API Calls", "type": "numeric" }, "limits": { "limit": 10000, "used": 10000, "remaining": 0 }, "reason": "resource_limit_exceeded", "error": { "code": 409, "message": "Monthly API call limit exceeded", "upgrade_url": "https://example.com/upgrade" } }

Webhook Integration

PaywallPro receives webhooks from payment gateways to automatically update subscription statuses. Each provider has a dedicated endpoint with signature verification.

Webhook Endpoints

Provider Endpoint Signature Header
Stripe /v1/webhooks/stripe Stripe-Signature
PayPal /v1/webhooks/paypal PAYPAL-TRANSMISSION-SIG
Paddle /v1/webhooks/paddle Paddle-Signature

All webhook endpoints return 202 Accepted immediately and process events asynchronously. Idempotency is handled automatically using event IDs.

Supported Events

  • subscription.created - New subscription started
  • subscription.updated - Subscription plan changed
  • subscription.cancelled - Subscription cancelled
  • payment.succeeded - Payment successfully processed
  • payment.failed - Payment failed
  • trial.ending - Trial ending in 3 days

Usage Tracking

Track feature usage for metered billing and analytics. Supports batching for high-volume events.

Record Usage Event

Track a single or batch of usage events

POST /v1/usage/events
Request Body (Single Event):
{ "subscriber_id": "sub_7f3a9b2c1d4e", "feature_code": "api_calls", "units": 1, "occurred_at": "2024-11-08T12:34:56Z", "metadata": { "endpoint": "/v1/subscribers", "method": "GET" } }
Request Body (Batch):
{ "events": [ { "subscriber_id": "sub_7f3a9b2c1d4e", "feature_code": "api_calls", "units": 1, "occurred_at": "2024-11-08T12:34:56Z" }, { "subscriber_id": "sub_7f3a9b2c1d4e", "feature_code": "storage_gb", "units": 2.5, "occurred_at": "2024-11-08T12:35:12Z" } ] }
Response (201 Created):
{ "recorded": 2, "events": [ { "id": "evt_abc123", "status": "recorded" }, { "id": "evt_def456", "status": "recorded" } ] }

Subscription Lifecycle

Endpoints

Method Endpoint Description
POST /v1/subscriptions/{id}/change-plan Upgrade or downgrade plan
POST /v1/subscriptions/{id}/cancel Cancel subscription
POST /v1/subscriptions/{id}/renew Manually renew subscription
POST /v1/subscriptions/{id}/reactivate Reactivate cancelled subscription

Change Subscription Plan

POST /v1/subscriptions/{id}/change-plan
Request Body:
{ "new_package_id": "pkg_professional", "prorate": true, "effective_date": "immediate" }
Response:
{ "subscription_id": "sub_7f3a9b2c1d4e", "old_package": "pkg_starter", "new_package": "pkg_professional", "effective_date": "2024-11-08T12:00:00Z", "proration_amount": 16.13, "next_billing_date": "2024-12-01T00:00:00Z", "status": "active" }

Cancel Subscription

POST /v1/subscriptions/{id}/cancel
Request Body:
{ "cancel_at_period_end": true, "reason": "switching_service", "feedback": "Found a better solution for our needs" }
Response:
{ "subscription_id": "sub_7f3a9b2c1d4e", "status": "active", "cancel_at_period_end": true, "cancelled_at": "2024-11-08T12:00:00Z", "current_period_end": "2024-12-01T00:00:00Z", "access_until": "2024-12-01T00:00:00Z" }

Error Handling

All API errors follow a consistent JSON structure with HTTP status codes and detailed error information.

Error Response Format

{ "error": { "code": "resource_not_found", "message": "Subscriber not found", "details": { "subscriber_id": "sub_invalid123" }, "request_id": "req_abc123xyz789", "timestamp": "2024-11-08T12:00:00Z" } }

HTTP Status Codes

Code Status Description
200 OK Request successful
201 Created Resource created successfully
202 Accepted Request accepted for processing
400 Bad Request Invalid request parameters
401 Unauthorized Invalid or missing authentication
403 Forbidden Insufficient permissions
404 Not Found Resource does not exist
409 Conflict Resource limit exceeded or duplicate request
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server-side error occurred

Common Error Codes

  • invalid_api_key - API key is invalid or expired
  • resource_not_found - Requested resource does not exist
  • resource_limit_exceeded - Feature usage limit reached
  • invalid_request - Request body validation failed
  • rate_limit_exceeded - Too many requests in time window
  • subscription_cancelled - Subscription is no longer active
  • payment_required - Payment method required to proceed