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
Stripe Integration Manage billing through Stripe Customer Portal Stripe

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 different feature limits

Note: Tier features and limits are discovered dynamically from services. Use the Limits API to query actual limits for each tier.

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 Usage Limits

  1. Query limits via GET /limits
  2. Returns all configured limits organized by service
  3. Query specific service or feature limits as needed

Monitoring Usage

  1. Query current usage via GET /limits/usage
  2. Returns usage statistics compared to tier limits
  3. Track consumption and approaching limits

Table of contents