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

Adjust a customer's outcome balance

Grant or claw back an outcome balance; the resulting balance is floored at zero.

POST
/customers/{id}/outcomes/adjust

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.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Grant (positive) or claw back (negative) an outcome balance; floored at zero.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/customers/cus_abc123/outcomes/adjust" \  -H "Content-Type: application/json" \  -d '{    "agentKey": "extract-clauses",    "delta": -3,    "notes": "Claw back unused contract-review runs"  }'
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "adjusted": true,    "remaining": 9  }}
{  "statusCode": 400,  "statusDetail": {    "status": "ERROR",    "message": "Request body must be valid JSON."  },  "result": {}}
{  "statusCode": 401,  "statusDetail": {    "status": "ERROR",    "message": "Invalid API key."  },  "result": {}}
{  "statusCode": 404,  "statusDetail": {    "status": "ERROR",    "message": "No customer with id \"cus_abc123\"."  },  "result": {}}
{  "statusCode": 422,  "statusDetail": {    "status": "ERROR",    "message": "No credit with agent key \"summarize\" exists in this workspace."  },  "result": {}}
{  "statusCode": 500,  "statusDetail": {    "status": "ERROR",    "message": "Could not complete the request."  },  "result": {}}

Adjust a customer's credit balance POST

Grant (positive `delta`) or claw back (negative `delta`) a credit balance.

Adjust a customer's unit balance POST

Grant (positive `delta`) or claw back (negative `delta`) a unit balance (fractional allowed); the resulting balance is floored at zero.

agentKey*string

An outcome STEP's stable agent key — identifies the parent outcome (outcomes have no key of their own).

Length1 <= length
delta*integer

Signed change: positive grants, negative claws back. Non-zero whole number; absolute value ≤ 10,000,000.

notes?string
Lengthlength <= 200