Tier Management (Admin)

Administrative endpoints for managing subscription tiers and billing system status. These endpoints require the billing_admin role.

Note on Features and Limits: As of the current implementation, tier features and limits are discovered dynamically from services rather than stored in the database. The features array in tier responses will always be empty. To query actual limits for a tier, use the Limits API endpoints instead.

Get All Subscription Tiers

View all subscription tiers with their features and limits. Admin only.

Endpoint: https://apis.threatwinds.com/api/billing/v1/admin/tiers

Method: GET

Parameters

Headers

Header	Type	Required	Description
Authorization	string	Optional*	Bearer token for session authentication
api-key	string	Optional*	API key for key-based authentication
api-secret	string	Optional*	API secret for key-based authentication

Note: You must use either Authorization header OR API key/secret combination.

Query Parameters

Parameter	Type	Required	Description	Default
active	boolean	No	Filter by active status	No filter

Required Roles

Required role: billing_admin

This endpoint requires the billing_admin role configured in the authentication system.

Request

To get all subscription tiers, use a GET request:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/admin/tiers' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Filter for active tiers only:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/admin/tiers?active=true' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Or using API key and secret:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/admin/tiers' \
  -H 'accept: application/json' \
  -H 'api-key: your-api-key' \
  -H 'api-secret: your-api-secret'

Response

Success Response (200 OK)

{
  "tiers": [
    {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "Free",
      "description": "Free tier for testing",
      "stripePriceId": "price_xxxxxxxxxxxxx",
      "isActive": true,
      "isDefault": true,
      "sortOrder": 0,
      "features": []
    },
    {
      "id": "770e8400-e29b-41d4-a716-446655440000",
      "name": "Professional",
      "description": "Professional tier with advanced features",
      "stripePriceId": "price_yyyyyyyyyyyyy",
      "isActive": true,
      "isDefault": false,
      "sortOrder": 1,
      "features": []
    },
    {
      "id": "880e8400-e29b-41d4-a716-446655440000",
      "name": "Enterprise",
      "description": "Enterprise tier with unlimited features",
      "stripePriceId": "price_zzzzzzzzzzzzz",
      "isActive": true,
      "isDefault": false,
      "sortOrder": 2,
      "features": []
    }
  ]
}

Response Schema

Field	Type	Description
tiers	array	List of subscription tiers
tiers[].id	string (UUID)	Tier unique identifier
tiers[].name	string	Tier name
tiers[].description	string	Tier description
tiers[].stripePriceId	string	Stripe price ID
tiers[].isActive	boolean	Whether tier is active
tiers[].isDefault	boolean	Whether tier is default for new customers
tiers[].sortOrder	integer	Display sort order
tiers[].features	array	Always empty (features discovered via service discovery)

Business Logic

Tiers are created and synced via Stripe webhooks when prices are created
Returns all tiers but features array is always empty
Features are now discovered dynamically: Use the /limits endpoints to query actual features and limits for a tier
Active filter defaults to showing both active and inactive tiers
Tier metadata (name, description, stripePriceId) stored in database
Feature limits are queried from individual services at runtime

Error Codes

Status Code	Description	Possible Cause
200	OK	Request successful
400	Bad Request	Invalid query parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Not billing_admin role

Set Default Subscription Tier

Set a tier as the default for new customer subscriptions. Admin only.

Endpoint: https://apis.threatwinds.com/api/billing/v1/admin/tiers/{tierID}/default

Method: PUT

Parameters

Headers

Header	Type	Required	Description
Authorization	string	Optional*	Bearer token for session authentication
api-key	string	Optional*	API key for key-based authentication
api-secret	string	Optional*	API secret for key-based authentication

Note: You must use either Authorization header OR API key/secret combination.

Path Parameters

Parameter	Type	Required	Description	Example
tierID	string (UUID)	Yes	Tier unique identifier	770e8400-e29b-41d4-a716-446655440000

Required Roles

Required role: billing_admin

Request

To set a tier as default, use a PUT request:

curl -X 'PUT' \
  'https://apis.threatwinds.com/api/billing/v1/admin/tiers/770e8400-e29b-41d4-a716-446655440000/default' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Or using API key and secret:

curl -X 'PUT' \
  'https://apis.threatwinds.com/api/billing/v1/admin/tiers/770e8400-e29b-41d4-a716-446655440000/default' \
  -H 'accept: application/json' \
  -H 'api-key: your-api-key' \
  -H 'api-secret: your-api-secret'

Response

Success Response (200 OK)

{
  "message": "Default tier updated successfully"
}

Business Logic

Only one tier can be default at a time
Tier must be active to be set as default
Clears previous default tier before setting new one
Default tier is used when creating new customer subscriptions
New customers automatically get subscribed to default tier

Error Codes

Status Code	Description	Possible Cause
200	OK	Default tier updated successfully
400	Bad Request	Invalid UUID, tier not active
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Not billing_admin role
404	Not Found	Tier not found

Get Billing System Status

Get system-wide billing statistics and metrics. Admin only.

Endpoint: https://apis.threatwinds.com/api/billing/v1/admin/billing/status

Method: GET

Parameters

Headers

Header	Type	Required	Description
Authorization	string	Optional*	Bearer token for session authentication
api-key	string	Optional*	API key for key-based authentication
api-secret	string	Optional*	API secret for key-based authentication

Note: You must use either Authorization header OR API key/secret combination.

Required Roles

Required role: billing_admin

Request

To get billing system status, use a GET request:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/admin/billing/status' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <token>'

Or using API key and secret:

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/admin/billing/status' \
  -H 'accept: application/json' \
  -H 'api-key: your-api-key' \
  -H 'api-secret: your-api-secret'

Response

Success Response (200 OK)

{
  "totalCustomers": 150,
  "activeCustomers": 120,
  "subscriptionsByTier": {
    "Pro": {
      "tierName": "Pro",
      "activeCustomers": 85,
      "avgMemberCount": 3.2
    },
    "Enterprise": {
      "tierName": "Enterprise",
      "activeCustomers": 35,
      "avgMemberCount": 5.7
    }
  }
}

Response Schema

Field	Type	Description
totalCustomers	integer	Total number of customers in system
activeCustomers	integer	Number of customers with active subscriptions
subscriptionsByTier	object	Statistics by tier name
subscriptionsByTier.{tier}	object	Tier-specific statistics
subscriptionsByTier.{tier}.tierName	string	Tier name
subscriptionsByTier.{tier}.activeCustomers	integer	Active customers on this tier
subscriptionsByTier.{tier}.avgMemberCount	float	Average team size for this tier

Business Logic

Counts total customers in system
Counts active customers (with active subscriptions)
Calculates statistics per tier:
- Number of active customers on that tier
- Average team member count per customer on that tier
Useful for monitoring growth and tier adoption

Error Codes

Status Code	Description	Possible Cause
200	OK	Request successful
400	Bad Request	Invalid request
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Not billing_admin role
500	Internal Server Error	Database query error

### Workflow 3: Monitor System Health

```bash
# Get billing system status
curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/admin/billing/status' \
  -H 'Authorization: Bearer <admin-token>'

# Analyze results:
# - Check active vs total customers ratio
# - Review tier distribution
# - Monitor average team sizes
# - Identify growth trends