Customer Management
Customer accounts represent organizations or teams in ThreatWinds. Each customer has a subscription tier, team members with roles, and associated usage limits.
Create Customer
Create a new customer account. The authenticated user automatically becomes the account owner.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer
Method: POST
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.
Request Body
{
"email": "john@doe.com"
}
| Parameter | Type | Required | Description |
|---|---|---|---|
| string | Yes | Customer email address |
Request
To create a customer account, use a POST request:
curl -X 'POST' \
'https://apis.threatwinds.com/api/billing/v1/customer' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
"email": "john@doe.com"
}'
Or using API key and secret:
curl -X 'POST' \
'https://apis.threatwinds.com/api/billing/v1/customer' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret' \
-H 'Content-Type: application/json' \
-d '{
"email": "john@doe.com"
}'
Response
A successful response will return the created customer information.
Success Response (201 Created)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"email": "john@doe.com",
"gcid": "cus_stripe_id_123"
}
Response Schema
| Field | Type | Description |
|---|---|---|
| id | string (UUID) | Customer unique identifier |
| string | Customer email address | |
| gcid | string | Stripe customer ID |
Business Logic
- User must not already be a member of any customer account
- Creates customer in Stripe and local database
- Automatically assigns caller as ROLE_OWNER (level 0)
- Creates default tier subscription via Stripe (webhook syncs to database)
- Returns error if no default subscription tier is configured
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 201 | Created | Customer created successfully |
| 400 | Bad Request | Invalid JSON, incorrect userID header, user already member of another customer |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Forbidden access |
| 500 | Internal Server Error | No default tier configured, Stripe error |
Get Customer
Retrieve customer account details for the authenticated user.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer
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: owner, admin, or user
Request
To retrieve customer information, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/customer' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/customer' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (200 OK)
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"gcid": "cus_stripe_id_123"
}
Response Schema
| Field | Type | Description |
|---|---|---|
| id | string (UUID) | Customer unique identifier |
| gcid | string | Stripe customer ID |
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 404 | Not Found | User not found or no customer |
| 400 | Bad Request | Invalid request |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Insufficient permissions |
Delete Customer
Permanently delete a customer account. Only the account owner can perform this action.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer
Method: DELETE
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: owner
This endpoint requires the owner role. Only the account owner can delete the customer.
Request
To delete a customer account, use a DELETE request:
curl -X 'DELETE' \
'https://apis.threatwinds.com/api/billing/v1/customer' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'DELETE' \
'https://apis.threatwinds.com/api/billing/v1/customer' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (204 No Content)
{
"message": "acknowledged"
}
Business Logic
- Only ROLE_OWNER can delete customer
- Deletes all member roles first
- Deletes customer in Stripe (webhook handles database deletion)
- Cancels all active subscriptions
- Cannot be undone
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 204 | No Content | Customer deleted successfully |
| 400 | Bad Request | User not owner |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Not authorized, insufficient permissions |
Leave Customer
Remove yourself from a customer account. Owners cannot use this endpoint and must transfer ownership first.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer/leave
Method: DELETE
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: admin or user
This endpoint requires the admin or user role. Owners cannot leave and must transfer ownership first.
Request
To leave a customer account, use a DELETE request:
curl -X 'DELETE' \
'https://apis.threatwinds.com/api/billing/v1/customer/leave' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'DELETE' \
'https://apis.threatwinds.com/api/billing/v1/customer/leave' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (204 No Content)
{
"message": "acknowledged"
}
Business Logic
- Removes user’s role from customer account
- Owner cannot use this endpoint (must transfer ownership first)
- User loses access to all customer resources
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 204 | No Content | Successfully left customer account |
| 400 | Bad Request | User is owner and cannot leave |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Insufficient permissions |
Get Customer Tier Information
Get detailed subscription tier information and status for the authenticated user’s customer account.
Endpoint: https://apis.threatwinds.com/api/billing/v1/customer/tier
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: owner, admin, or user
Request
To retrieve tier information, use a GET request:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/customer/tier' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'
Or using API key and secret:
curl -X 'GET' \
'https://apis.threatwinds.com/api/billing/v1/customer/tier' \
-H 'accept: application/json' \
-H 'api-key: your-api-key' \
-H 'api-secret: your-api-secret'
Response
Success Response (200 OK)
{
"customerId": "550e8400-e29b-41d4-a716-446655440000",
"tierId": "770e8400-e29b-41d4-a716-446655440000",
"tierName": "Professional",
"description": "Professional tier with advanced features",
"isActive": true,
"subscriptionStatus": "active"
}
Response Schema
| Field | Type | Description |
|---|---|---|
| customerId | string (UUID) | Customer unique identifier |
| tierId | string (UUID) | Subscription tier unique identifier |
| tierName | string | Tier name (e.g., “Free”, “Professional”, “Enterprise”) |
| description | string | Tier description |
| isActive | boolean | Whether the tier is active |
| subscriptionStatus | string | Current subscription status |
Subscription Status Values
| Status | Description |
|---|---|
| active | Active subscription, all features available |
| past_due | Payment overdue, features may be restricted |
| canceled | Subscription cancelled, access limited |
| paused | Temporarily paused |
| unpaid | Unpaid invoice, requires payment |
| incomplete | Incomplete payment setup |
Error Codes
| Status Code | Description | Possible Cause |
|---|---|---|
| 200 | OK | Request successful |
| 400 | Bad Request | Invalid request |
| 401 | Unauthorized | Missing or invalid authentication |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Customer not found or no active subscription |