Billing API

The ThreatWinds Billing API provides comprehensive billing, subscription, and team management capabilities powered by a payment processor integration. It enables customer account management, subscription tier control, usage limits tracking, and team collaboration features.

Overview

ThreatWinds Billing API allows you to:

Feature Description Documentation
Customer Management Create and manage customer accounts Customer Endpoints
Team Collaboration Add and manage team members with role-based access Team Management
Subscription Tiers View and manage subscription tiers Tier Management
Usage Limits Query tier-based usage limits for services Limits
Usage Weighting How chat completions and embeddings consume allowance by model Usage Weighting
Usage Tracking Monitor aggregated usage statistics and consumption Usage Tracking
Resource Quotas Query tier-based resource quotas and usage Resource Quotas
Granular Usage Owner/Admin-only per-event rate-limit and quota analytics Granular Usage
Billing Portal Manage billing through the customer portal Billing Portal
Admin (Customers) billing_admin-only customer administration Admin

Authentication

The Billing API supports two authentication methods:

Authentication Method Description
Bearer Token Session-based authentication using Authorization: Bearer <YOUR_BEARER_TOKEN> header
API Key API key authentication using api-key and api-secret headers

For details on how to obtain authentication credentials, see the Authentication section.

Role-Based Access Control

The Billing API implements a hierarchical role system for team collaboration:

Role API Value Description
Owner owner Full account control, can delete customer, transfer ownership, and manage billing
Admin admin Can manage team members and view customer info, limits, quotas, and usage
User user Read-only access to own customer info, limits, quotas, and usage; can leave account. Cannot access members, granular usage, or billing portal

Subscription Tiers

Subscription tiers are discovered dynamically from payment provider pricing data. The set of available tiers and their names may change over time. Use Get Customer Tier Information to check the current tier, or Tier Management (admin) to enumerate all tiers.

Note: Tier features and limits are discovered dynamically from services. Use the Limits API to query actual limits for each tier. A value of -1 means unlimited.

Rate Limiting

All API endpoints across ThreatWinds services are rate-limited based on your subscription tier. When a limit is exceeded, the API returns 429 Too Many Requests. Unauthenticated requests are limited by IP address using the Public tier.

Rate limits and quota features are discovered dynamically from connected services. Use the Limits API and Quotas API to query the current set of available limits.

For the full list of rate-limited features, see Usage Limits.

Resource Quotas

Some services enforce resource quotas that limit the total number of persistent resources you can provision (e.g., compute instances). Unlike rate limits, quotas have no time window. See Resource Quotas.

API Endpoints

The base URL for the Billing API is:

https://apis.threatwinds.com/api/billing/v1

For detailed information about each endpoint, please refer to the specific documentation pages.

Error Response Headers

All error responses include the following custom headers:

Header Description
x-error Human-readable error message describing what went wrong
x-error-id Unique identifier for error tracking and support

Error Codes

Status Code Description Possible Cause
200 OK Request successful (GET operations)
201 Created Customer or member created successfully
204 No Content Resource deleted or removed successfully
400 Bad Request Invalid parameters, malformed JSON, or validation error
401 Unauthorized Missing or invalid authentication credentials
403 Forbidden Insufficient permissions, role hierarchy violation, or not authorized
404 Not Found Customer, tier, member, or limits not found
500 Internal Server Error Server-side error

Common Workflows

Creating a Customer Account

  1. Create a customer account via POST /customer
  2. A default subscription tier is automatically assigned
  3. The creating user becomes the account owner

Managing Team Members

  1. Owner or Admin adds a member via POST /customer/member
  2. Member is assigned a role (Admin or User)
  3. Member can access customer resources based on their role

Transferring Ownership

  1. Current owner transfers ownership via POST /customer/transfer-ownership
  2. New owner must already be a member
  3. Current owner is demoted to Admin
  4. New owner is promoted to Owner

Checking Your Limits

  1. Query all your limits via GET /limits to see what’s available for your tier
  2. Query a specific service via GET /limits/{serviceName} (e.g., /limits/ai-api)
  3. Each limit includes the value, window, and description

Monitoring Usage

  1. Query current usage via GET /limits/usage to see current consumption
  2. Each feature shows currentUsage, limit, and remaining for the current time window
  3. For IP-based usage (unauthenticated), use GET /limits/usage/ip

Checking Quota Usage

  1. Query quota usage via GET /quotas/usage to see resource consumption
  2. Shows currentUsage vs limit for resources like compute instances
  3. When a quota is full, new resource creation returns 409 Conflict

Table of contents