Billing API

The ThreatWinds Billing API provides comprehensive billing, subscription, and team management capabilities powered by Stripe 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 Tracking Monitor aggregated usage statistics and consumption Usage Tracking
Resource Quotas Query tier-based resource quotas and usage Resource Quotas
Granular Usage Admin-only per-event rate-limit and quota analytics Granular Usage
Stripe Integration Manage billing through Stripe Customer Portal Stripe
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 <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 Level Description
Owner 0 Full account control, can delete customer, transfer ownership, and manage billing
Admin 1 Can manage team members and view customer info, limits, quotas, and usage
User 2 Read-only access to customer info, limits, quotas, usage, and can leave account

Subscription Tiers

The platform offers multiple subscription tiers with increasing limits:

Tier Target Audience
Public Unauthenticated / IP-based access
Free Individual users getting started
Pro Individual professionals
Pro Plus Power users
Business Small teams
Business Plus Growing teams
Business Max Large teams
Enterprise Organizations
Enterprise Plus Large organizations
Enterprise Max Custom / highest tier

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 are tracked across 5 services with 30 features total:

Service Features Windows Used
ai-api 8 minute, month
search-api 7 minute
compute-api 10 minute
feeds-api 3 minute, hour
analytics-api 2 minute

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
402 Payment Required Subscription tier member limit exceeded
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 real-time consumption
  2. Each feature shows currentUsage, limit, remaining, and resetAt
  3. Use resetAt timestamp to know when the counter resets
  4. 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 403 Forbidden

Table of contents