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
Manage

Manage a customer's wallet balance using customer Id

POST
/customers/{id}/wallet/adjust

Top up (positive delta) or draw down (negative delta) a customer's wallet, in USD. No agentKey — a customer has exactly one wallet. Works whatever the customer's plan — even with no plan — and the wallet may read negative. Send pool: "reserved" to move the Reserved Wallet instead (when your workspace has it on); remaining is then the Reserved balance, and a reduce below zero is refused (422). Send an idempotencyKey to make it safe to retry.

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 POST "https://example.com/customers/cus_abc123/wallet/adjust" \  -H "Content-Type: application/json" \  -d '{    "delta": 25,    "notes": "Goodwill top-up",    "idempotencyKey": "topup:ord_1042"  }'
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Wallet balance adjusted."  },  "result": {    "adjusted": true,    "replayed": false,    "remaining": 125.5,    "customerArchived": false  }}
{  "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": {}}

Manage a customer's wallet balance using external Id

POST
/customers/ext/{externalId}/wallet/adjust

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 POST "https://example.com/customers/ext/acme-42/wallet/adjust" \  -H "Content-Type: application/json" \  -d '{    "delta": 25,    "notes": "Goodwill top-up",    "idempotencyKey": "topup:ord_1042"  }'
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Wallet balance adjusted."  },  "result": {    "adjusted": true,    "replayed": false,    "remaining": 125.5,    "customerArchived": false  }}
{  "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": {}}

Manage a customer's composite balance POST

Previous Page

List a customer's members GET

Next Page

delta*number

Signed change in USD: positive tops up, negative draws down. Non-zero; cents allowed; absolute value ≤ 10,000,000.

notes?string
Lengthlength <= 200
pool?string

Which balance to move. main is the ordinary Wallet. reserved is the Reserved Wallet — a second balance behind the Wallet that a wallet-funded Arrear charge draws on once the Wallet runs out. It must be enabled for the workspace (Settings → Organisation → Billing → "Enable Reserved balance in wallet") and never goes below 0. A main adjustment never touches it. Leave pool out to move the Wallet; null, an empty string, or any other value (including the uppercase MAIN / RESERVED) is a 400.

Default"main"

Value in

  • "main"
  • "reserved"
idempotencyKey?string

Optional. Makes the adjustment safe to retry: a repeat with the same key and the same request adjusts nothing and returns replayed: true; the same key with a different request is a 422. Unique per workspace and per adjust endpoint. A failed adjustment never uses it up.

Length1 <= length <= 255
delta*number

Signed change in USD: positive tops up, negative draws down. Non-zero; cents allowed; absolute value ≤ 10,000,000.

notes?string
Lengthlength <= 200
pool?string

Which balance to move. main is the ordinary Wallet. reserved is the Reserved Wallet — a second balance behind the Wallet that a wallet-funded Arrear charge draws on once the Wallet runs out. It must be enabled for the workspace (Settings → Organisation → Billing → "Enable Reserved balance in wallet") and never goes below 0. A main adjustment never touches it. Leave pool out to move the Wallet; null, an empty string, or any other value (including the uppercase MAIN / RESERVED) is a 400.

Default"main"

Value in

  • "main"
  • "reserved"
idempotencyKey?string

Optional. Makes the adjustment safe to retry: a repeat with the same key and the same request adjusts nothing and returns replayed: true; the same key with a different request is a 422. Unique per workspace and per adjust endpoint. A failed adjustment never uses it up.

Length1 <= length <= 255