Admin — Customer Administration

Administrative endpoints for inspecting customer accounts across the platform. These endpoints require the caller to hold the billing_admin role.

Related: Tier administration lives on its own page — see Tier Management.

Table of Content:

List customers

List every customer in the billing system with optional pagination and filters. Returns a summary per customer — call Get customer details for the full record.

Endpoint: https://apis.threatwinds.com/api/billing/v1/admin/customers

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 the Authorization header OR the api-key/api-secret combination.

Query Parameters

Parameter Type Required Description Example
page int No Page number (default 1). 1
limit int No Items per page (default 10, max 100). 10
tierName string No Filter by subscription tier name. pro
status string No Filter by Stripe subscription status (active, past_due, canceled, unpaid). active

Request 

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/admin/customers?page=1&limit=10&status=active' \
  -H 'Authorization: Bearer <token>'

Response

Success Response (200 OK) 

{
  "customers": [
    {
      "id": "a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e",
      "name": "Acme Corp",
      "tierName": "pro",
      "subscriptionStatus": "active",
      "memberCount": 12,
      "createdAt": "2026-02-03T09:14:22Z",
      "ownerUserID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e"
    }
  ],
  "items": 1,
  "pages": 1
}

Response Schema

Field Type Description
customers array Array of customer summary objects.
customers[].id string Customer UUID.
customers[].name string Customer display name.
customers[].tierName string Current subscription tier name.
customers[].subscriptionStatus string Stripe subscription status.
customers[].memberCount int Number of team members currently on the account.
customers[].createdAt string ISO 8601 timestamp the customer was created.
customers[].ownerUserID string UUID of the account owner. Zero UUID for orphaned customers.
items int Total number of items matching the query.
pages int Total number of pages available.

Error Codes

Status Description Cause
200 OK Success.
400 Bad Request Invalid query parameters.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the billing_admin role.

Get customer details

Retrieve the full administrative record for a single customer — including subscription state, tier, member count, and the account owner’s user ID.

Endpoint: https://apis.threatwinds.com/api/billing/v1/admin/customer/{customerID}

Method: GET

Parameters

Headers

Same as List customers.

Path Parameters

Parameter Type Required Description Example
customerID string Yes Customer UUID. “a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e”

Request 

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/admin/customer/a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e' \
  -H 'Authorization: Bearer <token>'

Response

Success Response (200 OK) 

{
  "id": "a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e",
  "name": "Acme Corp",
  "createdAt": "2026-02-03T09:14:22Z",
  "tierName": "pro",
  "tierID": "e1f2a3b4-5633-4b16-bbf0-5ca22ef8ea2e",
  "subscriptionStatus": "active",
  "memberCount": 12,
  "ownerUserID": "5f35d2c4-5633-4b16-bbf0-5ca22ef8ea2e"
}

Response Schema

Field Type Description
id string Customer UUID.
name string Customer display name.
createdAt string ISO 8601 timestamp the customer was created.
tierName string Current subscription tier name.
tierID string UUID of the current subscription tier.
subscriptionStatus string Stripe subscription status (active, past_due, canceled, trialing, paused, unpaid).
memberCount int Number of team members currently on the account.
ownerUserID string UUID of the account owner.

Error Codes

Status Description Cause
200 OK Success.
400 Bad Request Invalid customerID format.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the billing_admin role.
404 Not Found No customer with the given ID exists.

Delete any customer

Force-delete any customer regardless of ownership. Triggers the same cascade as owner-initiated deletion. See Account Deletion Cascade.

Endpoint: https://apis.threatwinds.com/api/billing/v1/admin/customer/{customerID}

Method: DELETE

Parameters

Headers

Same as List all customers.

Path Parameters

Parameter Type Required Description Example
customerID string Yes Customer ID (UUID) a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e

Request 

curl -X 'DELETE' \
  'https://apis.threatwinds.com/api/billing/v1/admin/customer/a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e' \
  -H 'Authorization: Bearer <token>'

Response

204 No Content on success.

Error Codes

Status Description Cause
204 No Content Customer and all its dependent resources deleted.
400 Bad Request Invalid customer ID (not a UUID).
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the billing_admin role.
404 Not Found No customer with the given ID exists.
500 Internal Server Error Stripe or DB error during cascade.

List members of any customer

List every member of any customer regardless of caller membership. Useful for cross-customer audits. Returns {members[], items, pages}.

Endpoint: https://apis.threatwinds.com/api/billing/v1/admin/customer/{customerID}/members

Method: GET

Parameters

Headers

Same as List customers.

Path Parameters

Parameter Type Required Description Example
customerID string Yes Customer ID (UUID) a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e

Query Parameters

Parameter Type Required Description
page integer No Page number (default: 1).
limit integer No Items per page (default: 10, max: 100).

Request 

curl -X 'GET' \
  'https://apis.threatwinds.com/api/billing/v1/admin/customer/a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e/members?page=1&limit=10' \
  -H 'Authorization: Bearer <token>'

Response 

{
  "members": [
    {
      "roleID": "46482dce-8984-474c-be6a-5dde51632cca",
      "userID": "ea04845b-d127-4bd6-ae1b-b5ef40a3a7a7",
      "role": "owner"
    },
    {
      "roleID": "a2576efd-31fb-4728-b232-df958d41bd5d",
      "userID": "706a116f-0236-460e-8f08-9a65a2da89c2",
      "role": "admin"
    }
  ],
  "items": 2,
  "pages": 1
}

Error Codes

Status Description Cause
200 OK Members returned.
400 Bad Request Invalid customerID.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the billing_admin role.
404 Not Found No customer with the given ID exists.
500 Internal Server Error Database error.

Add a member to any customer

Attach a user as admin or user member to any customer. The owner role is reserved — use Transfer Ownership (owner-driven, not admin).

Endpoint: https://apis.threatwinds.com/api/billing/v1/admin/customer/{customerID}/member

Method: POST

Parameters

Headers

Parameter Type Required Description
Content-Type string Yes Must be application/json.
Authorization string Yes Bearer <token> or api-key/api-secret.

Path Parameters

Parameter Type Required Description Example
customerID string Yes Customer ID (UUID) a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e

Body 

{
  "userID": "9de7068a-2422-46c1-b718-4a95a91cd559",
  "role": "user"
}
Field Type Required Description
userID string Yes UUID of the user to add.
role string Yes One of admin, user. owner rejected.

Role format: The API accepts role as a string (preferred): "owner", "admin", or "user". For backwards compatibility, the legacy integer values 0, 1, 2 are also accepted on input. All responses use the canonical string names. The "owner" role cannot be assigned via this endpoint — use Transfer Ownership.

Request 

curl -X 'POST' \
  'https://apis.threatwinds.com/api/billing/v1/admin/customer/a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e/member' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"userID":"9de7068a-2422-46c1-b718-4a95a91cd559","role":"user"}'

Response

201 Created on success:

{ "message": "acknowledged" }

Error Codes

Status Description Cause
201 Created Membership row inserted.
400 Bad Request Invalid customerID, malformed body, owner role requested, or invalid role.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the billing_admin role.
404 Not Found No customer with the given ID exists.
409 Conflict User is already a member of a customer (single-tenant per user).
500 Internal Server Error Database error.

Remove a member from any customer

Detach a user from a customer. Owner cannot be removed — use Transfer Ownership first.

Endpoint: https://apis.threatwinds.com/api/billing/v1/admin/customer/{customerID}/member/{userID}

Method: DELETE

Parameters

Headers

Same as List customers.

Path Parameters

Parameter Type Required Description Example
customerID string Yes Customer ID (UUID) a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e
userID string Yes User ID (UUID) 9de7068a-2422-46c1-b718-4a95a91cd559

Request 

curl -X 'DELETE' \
  'https://apis.threatwinds.com/api/billing/v1/admin/customer/a1b2c3d4-5633-4b16-bbf0-5ca22ef8ea2e/member/9de7068a-2422-46c1-b718-4a95a91cd559' \
  -H 'Authorization: Bearer <token>'

Response

204 No Content on success.

Error Codes

Status Description Cause
204 No Content Membership removed.
400 Bad Request Invalid customerID or userID.
401 Unauthorized Missing or invalid credentials.
403 Forbidden Caller does not hold the billing_admin role.
404 Not Found Customer not found, or user is not a member of it.
409 Conflict User is the owner — transfer ownership first.
500 Internal Server Error Database error.