Credits & Limits

Credit System

LusterCMS uses a credit-based system for AI features and resource management.

Credit Flow

SUPERADMIN
    │
    │ grants credits
    ▼
ADMIN (credit_balance)
    │
    │ sets credit_limit
    ▼
ORGANIZATION (credit_limit + credit_balance - credit_used)
    │
    │ uses credits
    ▼
AI FEATURES

Organization Credits

Each organization has three credit-related values:

Field	Description
credit_limit	Maximum credits allocated by Admin
credit_balance	Credits purchased directly by organization
credit_used	Total credits consumed

Available Credits = credit_limit + credit_balance - credit_used

Admin Credit Pool

Admins maintain their own credit pool:

Field	Description
credit_balance	Current available credits
total_purchased	Total credits ever purchased
total_granted_by_superadmin	Credits granted by platform owner
total_distributed_to_orgs	Credits distributed to organizations

Resource Limits

Each organization has resource limits:

Limit	Default	Description
storage_limit_gb	10 GB	Maximum file storage
max_users	10	Maximum user accounts
bandwidth_limit_gb	100 GB/month	Monthly bandwidth limit

Usage Tracking

The system automatically tracks:

• Storage: Total bytes used by uploaded files
• Users: Current number of active users
• Bandwidth: Monthly data transfer (resets automatically)

API Endpoints

Grant Credits to Admin (Superadmin only)

POST /api/tenants/admins/{admin_id}/grant-credits
Authorization: Bearer {superadmin_token}
Content-Type: application/json

{
  "admin_id": 1,
  "amount": 10000,
  "reason": "Monthly allocation"
}

Set Organization Credit Limit (Admin/Superadmin)

PUT /api/tenants/organizations/{org_id}/credit-limit
Authorization: Bearer {token}
Content-Type: application/json

{
  "credit_limit": 5000
}

Add Direct Credits to Organization

POST /api/tenants/organizations/{org_id}/credits/add
Authorization: Bearer {token}
Content-Type: application/json

{
  "amount": 1000,
  "reason": "Credit purchase"
}

Get Organization Usage

GET /api/tenants/organizations/{org_id}/usage
Authorization: Bearer {token}

Response:

{
  "storage": {
    "used_gb": 2.5,
    "limit_gb": 10,
    "usage_percent": 25.0
  },
  "users": {
    "current_count": 5,
    "max_users": 10,
    "usage_percent": 50.0
  },
  "bandwidth": {
    "used_gb": 45.2,
    "limit_gb": 100,
    "usage_percent": 45.2
  },
  "credits": {
    "limit": 5000,
    "balance": 1000,
    "used": 2500,
    "available": 3500
  }
}

Update Organization Limits (Superadmin only)

PUT /api/tenants/organizations/{org_id}/limits
Authorization: Bearer {superadmin_token}
Content-Type: application/json

{
  "storage_limit_gb": 20,
  "max_users": 25,
  "bandwidth_limit_gb": 200
}

Notifications

The system sends notifications when:

• Credits are running low (< 20% remaining)
• Credits are depleted
• Storage limit is approaching (> 80%)
• Storage limit reached
• Bandwidth limit approaching

Best Practices

1. Set Reasonable Defaults: Configure sensible default limits in Platform Settings
2. Monitor Usage: Regularly check organization usage dashboards
3. Communicate Limits: Ensure customers understand their limits
4. Handle Overages: Decide policy for limit violations (block, warn, or charge)