Tier Management (Admin)

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

Note: To query actual features and limits for a tier, use the Limits API endpoints.

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	true (active tiers only)

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	Tier features list

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"
}

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

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	Server error

---