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
pageSize int No Page size (default 20, max 100). 20
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&pageSize=20&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"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalCount": 342,
    "totalPages": 18,
    "hasNext": true,
    "hasPrev": false
  }
}

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.
pagination object Standard pagination envelope.

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",
  "subscriptionEnabled": true,
  "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.
subscriptionEnabled bool Whether the subscription is active and in good standing.
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.