ClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Good to know

Response formatHandling errorsPaginating resultsSending data reliablyYour own customer idsWebhooks

API reference

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POST
List customers GETCreate a customer POSTGet a customer GETUpdate a customer PATCHDelete a customer DELETEGet a customer's balances GETGet a customer's wallet ledger GETSet a customer's low-balance alert PUTGet a customer's current plan GETChange a recurring grant PUTList Customer Usage Log GETLook Up Usage Logs by ID GET
Manage a customer's credit balance POSTManage a customer's outcome balance POSTManage a customer's unit balance POSTManage a customer's composite balance POSTManage a customer's wallet balance POST
List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE
PlansCreditsOutcomesUnitsComposites
List taxes GETCreate a tax POSTGet a tax GETUpdate a tax PATCH
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
wallet.balance.update POSTwallet.balance.drop POST
Mint a customer-portal access token POST
Customers

Change a recurring grant using customer Id

PUT
/customers/{id}/recurring-grant

Updates how much a customer is granted every cycle. Any increase or decrease applies to their balance immediately.

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

Path Parameters

id*string

Customer id.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/customers/cus_abc123/recurring-grant" \  -H "Content-Type: application/json" \  -d '{    "kind": "wallet",    "quantity": 10000  }'
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Recurring grant updated."  },  "result": {    "updated": true,    "kind": "wallet",    "quantity": 10000,    "balanceUsd": 125000  }}
{  "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": {}}

Change a recurring grant using external Id

PUT
/customers/ext/{externalId}/recurring-grant

The same call, addressed by the customer's externalId. Same body and response.

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

Path Parameters

externalId*string

Your own id for the customer (its externalId): 1–32 letters, numbers or "-", matched exactly (case-sensitive).

Match^[A-Za-z0-9-]{1,32}$
Length1 <= length <= 32

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/customers/ext/acme-42/recurring-grant" \  -H "Content-Type: application/json" \  -d '{    "kind": "wallet",    "quantity": 10000  }'
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Recurring grant updated."  },  "result": {    "updated": true,    "kind": "wallet",    "quantity": 10000,    "balanceUsd": 125000  }}
{  "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": {}}

Get a customer's current plan GET

Previous Page

List Customer Usage Log GET

One customer's usage history — credit, outcome, unit, wallet and completed composite occurrences — merged into one feed sorted by time. Cursor-paginated: pass `limit`/`cursor` and read `nextCursor` back; `null` means the last page. Narrow by date with `from`/`to`.

kind*string

What to change.

Value in

  • "wallet"
  • "credit"
  • "outcome"
  • "unit"
  • "composite"
agentKey?string

Which credit, outcome step, unit or composite to change. Not needed for wallet.

Length1 <= length
quantity*number

The new amount per billing cycle. USD for wallet, a whole number for everything else.

Range0 <= value <= 10000000
kind*string

What to change.

Value in

  • "wallet"
  • "credit"
  • "outcome"
  • "unit"
  • "composite"
agentKey?string

Which credit, outcome step, unit or composite to change. Not needed for wallet.

Length1 <= length
quantity*number

The new amount per billing cycle. USD for wallet, a whole number for everything else.

Range0 <= value <= 10000000