Skip to content

Payment & Subscription API

The Payment API handles subscription management, billing, and usage tracking.

Endpoints

Get Subscription Status

GET /api/v1/payment/subscription

Response: 

{
  "success": true,
  "subscription": {
    "tier": "professional",
    "status": "active",
    "currentPeriodStart": "2025-08-01T00:00:00Z",
    "currentPeriodEnd": "2025-09-01T00:00:00Z",
    "usage": {
      "orchestratorRuns": 45,
      "teamDeployments": 12,
      "apiCalls": 1250
    },
    "limits": {
      "orchestratorRuns": 1000,
      "teamDeployments": 50,
      "apiCalls": 10000
    }
  }
}

Create Subscription

POST /api/v1/payment/subscription

Request Body: 

{
  "tier": "professional",
  "payment_token": "tok_visa_1234"
}

Response: 

{
  "success": true,
  "subscription": {
    "id": "sub_123",
    "tier": "professional",
    "status": "active",
    "amount": 29.99,
    "currency": "USD"
  }
}

Update Subscription

PUT /api/v1/payment/subscription

Request Body: 

{
  "tier": "enterprise"
}

Cancel Subscription

DELETE /api/v1/payment/subscription

Response: 

{
  "success": true,
  "message": "Subscription cancelled",
  "effective_date": "2025-09-01T00:00:00Z"
}

Get Usage Statistics

GET /api/v1/payment/usage

Response: 

{
  "success": true,
  "userId": "user_123",
  "currentUsage": {
    "orchestratorRuns": 45,
    "teamDeployments": 12,
    "apiCalls": 1250
  },
  "limits": {
    "orchestratorRuns": 1000,
    "teamDeployments": 50,
    "apiCalls": 10000
  },
  "utilizationPercentage": {
    "orchestratorRuns": 4.5,
    "teamDeployments": 24.0,
    "apiCalls": 12.5
  },
  "resetDate": "2025-09-01T00:00:00Z"
}

Subscription Tiers

Free Tier

  • Price: $0/month
  • Orchestrator Runs: 10/month
  • Team Deployments: 2/month
  • API Calls: 1,000/month
  • Support: Community

Professional Tier

  • Price: $29.99/month
  • Orchestrator Runs: 1,000/month
  • Team Deployments: 50/month
  • API Calls: 10,000/month
  • Support: Email

Enterprise Tier

  • Price: $99.99/month
  • Orchestrator Runs: Unlimited
  • Team Deployments: Unlimited
  • API Calls: Unlimited
  • Support: Priority + Phone

Usage Tracking

The system tracks usage across these metrics: - Orchestrator Runs - Each orchestrator execution - Team Deployments - Active team deployments - API Calls - REST API requests - WebSocket Connections - Real-time connections - Storage Usage - Data and file storage

Billing Cycle

  • Monthly billing on subscription date
  • Prorated charges for tier changes
  • Usage resets on billing date
  • Overage charges apply for exceeded limits

Payment Methods

Supported payment methods: - Credit Cards (Visa, MasterCard, Amex) - PayPal - Bank Transfer (Enterprise only) - Cryptocurrency (Beta)

Webhooks

Subscribe to billing events:

{
  "events": [
    "subscription.created",
    "subscription.updated", 
    "subscription.cancelled",
    "payment.succeeded",
    "payment.failed",
    "usage.limit_reached"
  ]
}

Error Codes

Payment Errors

  • PAYMENT_FAILED - Payment processing failed
  • INVALID_CARD - Invalid payment method
  • INSUFFICIENT_FUNDS - Insufficient funds
  • EXPIRED_CARD - Payment method expired

Subscription Errors

  • TIER_NOT_FOUND - Invalid subscription tier
  • SUBSCRIPTION_NOT_FOUND - Subscription doesn't exist
  • ALREADY_SUBSCRIBED - User already has active subscription
  • CANCELLATION_FAILED - Unable to cancel subscription

Usage Errors

  • LIMIT_EXCEEDED - Usage limit exceeded
  • QUOTA_EXHAUSTED - Monthly quota used up
  • BILLING_REQUIRED - Payment method required

Generated on 2025-08-12 14:48:04