/ Documentation

Subscription Policies API

Production Ready

Manage subscription plans, feature limits, and usage validation for the SaaS platform.

Overview

The Subscription Policies API provides comprehensive plan management with 4 tiers: Free, Professional, Small Teams, and Enterprise. Each plan has specific limits for machines, users, storage, API calls, and features.

Subscription Plans

API Endpoints

20+

Limits per Plan

15+

Feature Flags

Base URL

https://sapienstream.com/api/subscription-policies

Endpoints

List Subscription Plans

GET

Retrieve all available subscription plans

curl -X GET "https://sapienstream.com/api/subscription-policies/plans" \
  -H "Accept: application/json"

Response

["free", "professional", "small_teams", "enterprise"]

Get Plan Details

GET

Get detailed information about a specific plan

curl -X GET "https://sapienstream.com/api/subscription-policies/plans/{plan_name}" \
  -H "Accept: application/json"

Response Example (Professional Plan)

{
  "name": "professional",
  "display_name": "Professional",
  "description": "Advanced features for growing businesses and teams",
  "monthly_price": 29.0,
  "annual_price": 290.0,
  "currency": "USD",
  "limits": {
    "max_users": 5,
    "max_machines": 25,
    "max_tags_per_machine": 500,
    "max_storage_gb": 25.0,
    "max_api_calls_per_hour": 10000
  },
  "features": {
    "advanced_analytics": true,
    "custom_dashboards": true,
    "priority_support": true,
    "api_access": true
  }
}

Check Plan Limit

POST

Validate if current usage is within plan limits

curl -X POST "https://sapienstream.com/api/subscription-policies/check-limit" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_name": "professional",
    "limit_name": "max_machines",
    "current_value": 15
  }'

Response

{
  "plan_name": "professional",
  "limit_name": "max_machines",
  "current_value": 15,
  "limit_value": 25,
  "within_limit": true,
  "usage_percentage": 60.0
}

Check Feature Availability

GET

Check if a feature is available in a plan

curl -X GET "https://sapienstream.com/api/subscription-policies/plans/professional/features/advanced_analytics" \
  -H "Accept: application/json"

Response

{
  "plan_name": "professional",
  "feature_name": "advanced_analytics",
  "available": true
}

Get Plan Limits

GET

Get all limits for a specific plan

curl -X GET "https://sapienstream.com/api/subscription-policies/plans/professional/limits" \
  -H "Accept: application/json"

Response

{
  "plan_name": "professional",
  "limits": {
    "max_users": 5,
    "max_machines": 25,
    "max_tags_per_machine": 500,
    "max_storage_gb": 25.0,
    "max_api_calls_per_hour": 10000,
    "max_webhooks": 10,
    "max_custom_dashboards": 5,
    "max_alerts": 50,
    "support_level": "standard",
    "uptime_sla": 0.9950
  }
}

Demo Usage Scenarios

GET

Get sample usage scenarios for testing

curl -X GET "https://sapienstream.com/api/subscription-policies/demo/usage-scenarios" \
  -H "Accept: application/json"

Response

{
  "demo_scenarios": [
    {
      "scenario_name": "Small Startup",
      "plan_name": "free",
      "plan_display_name": "Free",
      "usage": {
        "users": 1,
        "machines": 2,
        "storage_gb": 0.5
      },
      "limits_check": {
        "users": {
          "current": 1,
          "limit": 1,
          "within_limit": true
        }
      },
      "all_within_limits": true,
      "recommendation": "✅ Good fit"
    }
  ]
}

Plan Comparison

Feature	Free	Professional	Small Teams	Enterprise
Monthly Price	$0	$29	$145	Custom
Max Users	1	5	15	100
Max Machines	1	5	100	Unlimited
Storage	1 GB	10 GB	50 GB	Unlimited
API Calls/Hour	1,000	10,000	50,000	Unlimited
Advanced Analytics
Priority Support

Error Responses

400 - Bad Request

{
  "detail": "Invalid plan name: 'invalid_plan'"
}

404 - Not Found

{
  "detail": "Plan 'nonexistent' not found"
}

422 - Validation Error

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "plan_name"],
      "msg": "Field required"
    }
  ]
}

Implementation Notes

Production Ready

The Subscription Policies API is fully deployed and operational on production at sapienstream.com. All endpoints have been tested with sub-3ms response times and comprehensive validation.

• All plans are configured via YAML files in the /policies directory
• Plan limits are enforced by middleware throughout the application
• Features are validated using feature flags defined in the plan configuration
• The API supports both exact limit checking and percentage-based usage reporting
• Demo scenarios provide realistic testing data for frontend integration
• All responses include comprehensive validation and error handling