ClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Core concepts

The response envelopeErrorsPaginationAsync, flushing & reliability

API reference

Record Signals POSTRecord usage logs POST
List customers GETCreate a customer POSTGet a customer GETUpdate a customer PATCHDelete a customer DELETEGet a customer's balances GETGet a customer's current plan GETList a customer's wallet transactions GETAdd a wallet transaction POSTAdjust a customer's credit balance POSTAdjust a customer's outcome balance POSTAdjust a customer's unit balance POST
List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE
List purchases GETCreate a purchase POSTGet a purchase GETUpdate a purchase's auto-payment setting PATCHCancel a purchase POST
List invoices GETGet an invoice GETMint a hosted pay link GET
List payments GETGet a payment GET
Mint a customer-portal access token POST
Customers

Get a customer's balances

Wallet, credit, outcome and unit balances under the customer's current plan. When `hasPlan` is false the balance collections are empty and `wallet` is null.

GET
/customers/{id}/balances

Authorization

apiKey
AuthorizationBearer <token>

Per-organisation API key from Settings → API Keys, sent as Authorization: Bearer cnk_…. Missing, unknown or expired keys return 401.

In: header

Path Parameters

id*string

Customer id.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/cus_abc123/balances"
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "customerId": "cus_abc123",    "currency": {      "code": "USD",      "rateUsd": 1    },    "hasPlan": true,    "wallet": {      "balanceUsd": 262.5    },    "credits": [      {        "creditId": "cred_pqr678",        "agentKey": "deep-research",        "creditName": "Deep Research",        "granted": 5000,        "used": 1240,        "remaining": 3760      }    ],    "outcomes": [      {        "outcomeId": "out_stu901",        "outcomeName": "Contract review",        "granted": 12,        "remaining": 9,        "steps": [          {            "id": "step_1",            "name": "extract-clauses",            "agentKey": "extract-clauses"          }        ]      }    ],    "units": [      {        "unitId": "unit_vwx234",        "agentKey": "seats",        "unitName": "Seats",        "granted": 50,        "remaining": 37.5      }    ]  }}
{  "statusCode": 401,  "statusDetail": {    "status": "ERROR",    "message": "Invalid API key."  },  "result": {}}
{  "statusCode": 404,  "statusDetail": {    "status": "ERROR",    "message": "No customer with id \"cus_abc123\"."  },  "result": {}}
{  "statusCode": 500,  "statusDetail": {    "status": "ERROR",    "message": "Could not complete the request."  },  "result": {}}

Delete a customer DELETE

Cascades members, invitations and usage logs.

Get a customer's current plan GET

`plan` is null when there is no SCHEDULED or ACTIVE purchase.