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
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 and transfer ownership
Admin 1 Can manage team members and view limits
User 2 Read-only access to customer information and limits

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 MD5 hash 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 limit exceeded
403 Forbidden Insufficient permissions, role hierarchy violation, or not authorized
404 Not Found Customer, tier, member, or limits not found
409 Conflict Duplicate tier or conflicting operation
412 Precondition Failed User already member or business logic validation failed
500 Internal Server Error Database error, Stripe sync failure, or server-side error
501 Not Implemented Feature not yet implemented (e.g., payment method update)

Stripe Integration

The Billing API is deeply integrated with Stripe for payment processing and subscription management:

  • Automatic Sync: Stripe webhooks automatically sync subscription changes to the database
  • Customer Portal: Owners can access the Stripe Customer Portal to manage billing
  • Tier Management: Subscription tiers are created and managed through Stripe prices
  • Payment Processing: All payment and invoice processing handled by Stripe

Common Workflows

Creating a Customer Account

  1. User creates a customer account via POST /customer
  2. System creates customer in Stripe
  3. Stripe webhook creates default tier subscription
  4. User becomes account owner

Managing Team Members

  1. Owner/Admin adds member via POST /customer/member
  2. System validates tier member limits
  3. Member assigned role (Admin or User)
  4. Member can access customer resources based on role

Transferring Ownership

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

Checking Usage Limits

  1. Authenticated user queries limits via GET /limits
  2. System retrieves customer’s subscription tier
  3. Returns all configured limits organized by service
  4. User can query specific service or feature limits

Monitoring Usage

  1. User queries current usage via GET /usage
  2. System aggregates usage across all services
  3. Returns usage statistics compared to tier limits
  4. User can track consumption and approaching limits
  5. Application displays warnings when nearing quota

Table of contents