Customers

Operator-level endpoints for managing customer balances and usage. Requires a platform key — these endpoints are not available with session tokens.

Auth: Platform key (sk_pj_*) only.

Use AdminBillingClient in the SDK:

import { AdminBillingClient } from '@assistant-billing/sdk';
 
const admin = new AdminBillingClient({
  platformKey: process.env.ASSISTANT_BILLING_PLATFORM_KEY,
  baseURL: 'https://api.assistant-billing.dev/v1/platform',
});

List Customers

GET /v1/platform/customers

Returns all customers (workspaces) with their current balances.

Query Parameters

Name	Type	Required	Description
`limit`	number	No	Results per page. Default: 20
`offset`	number	No	Results to skip. Default: 0

const { data } = await admin.customers.list({ limit: 50 })

Response

{
  "data": [
    {
      "workspace_id": "ws_team_123",
      "balance_usd": "142.350000",
      "min_balance_usd": "0.000000",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-15T12:30:00.000Z"
    }
  ]
}

Get Customer Balance

GET /v1/platform/customers/:workspace_id/balance

Returns the current balance for a specific customer.

Path Parameters

Param	Type	Required	Description
`workspace_id`	string	Yes	Workspace identifier

const balance = await admin.customers.getBalance('ws_team_123')

Response

{
  "workspace_id": "ws_team_123",
  "balance": "142.350000",
  "sufficient": true
}

Get Customer Transactions

GET /v1/platform/customers/:workspace_id/transactions

Returns transaction history for a customer, most recent first.

Path Parameters

Param	Type	Required	Description
`workspace_id`	string	Yes	Workspace identifier

Query Parameters

Name	Type	Required	Description
`limit`	number	No	Results per page. Default: 50, maximum: 100
`offset`	number	No	Number of results to skip. Default: 0. Cannot be combined with `cursor`
`cursor`	string	No	Opaque `next_cursor` from the previous page. Cannot be combined with `offset`
`type`	string	No	Comma-separated list of `credit`, `debit`, `refund`, `adjustment` to include
`exclude_type`	string	No	Comma-separated list of those transaction types to exclude

Results are ordered by created_at DESC, id DESC.

const { data, next_cursor } = await admin.customers.getTransactions('ws_team_123', {
  limit: 10,
  type: ['credit', 'refund'],
})

Response

{
  "data": [
    {
      "id": "txn_a1b2c3d4",
      "type": "debit",
      "amount_usd": "-0.003420",
      "balance_after": "142.346580",
      "description": "gpt-4o — 150 tokens",
      "reference_type": "api_request",
      "created_at": "2025-01-15T12:30:00.000Z"
    }
  ],
  "next_cursor": "WyIyMDI1LTAxLTE1IDEyOjMwOjAwLjAwMDAwMCIsInR4bl9hMWIyYzNkNCJd"
}

next_cursor is always present. Pass it as cursor to read the next page. null means there are no more results. Keep the same filters when paging.

Get Customer Usage

GET /v1/platform/customers/:workspace_id/usage

Returns usage statistics for a customer over a date range.

Path Parameters

Param	Type	Required	Description
`workspace_id`	string	Yes	Workspace identifier

Query Parameters

Name	Type	Required	Description
`from`	string	Yes	Start date (ISO 8601)
`to`	string	Yes	End date (ISO 8601)

const usage = await admin.customers.getUsage('ws_team_123', {
  from: '2025-01-01',
  to: '2025-01-31',
})

Response

{
  "total_requests": 4250,
  "total_cost": "18.450000",
  "total_input_tokens": "850000",
  "total_output_tokens": "400000"
}