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

Update a customer using customer Id

PATCH
/customers/{id}

Partial update. Any field sent as null clears that optional column; omitted fields are left untouched. An externalId already held by another active customer is a 409.

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.

All fields optional; omitted fields are left untouched.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/customers/cus_abc123" \  -H "Content-Type: application/json" \  -d '{    "name": "Acme Inc",    "externalId": "acme-42",    "description": "AI meeting-notes startup — growth tier",    "email": "ops@acme.com",    "website": "https://acme.com",    "phone": "+1 415 555 0100",    "legalName": "Acme Incorporated",    "addressLine1": "500 Market Street",    "city": "San Francisco",    "state": "CA",    "country": "United States",    "pincode": "94105",    "taxId": "US-EIN 12-3456789",    "currencyCode": "USD"  }'
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "customer": {      "id": "cus_abc123",      "externalId": "acme-42",      "slug": "acme-inc",      "name": "Acme Inc",      "description": "AI meeting-notes startup — growth tier",      "email": "ops@acme.com",      "website": "https://acme.com",      "phone": "+1 415 555 0100",      "legalName": "Acme Incorporated",      "addressLine1": "500 Market Street",      "city": "San Francisco",      "state": "CA",      "country": "United States",      "pincode": "94105",      "taxId": "US-EIN 12-3456789",      "currencyCode": "USD",      "createdAt": "2026-07-01T09:30:00.000Z",      "updatedAt": "2026-07-18T11:12:00.000Z"    }  }}
{  "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": 409,  "statusDetail": {    "status": "ERROR",    "message": "Customer \"cus_abc123\" is archived."  },  "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": {}}

Update a customer using external Id

PATCH
/customers/ext/{externalId}

The same call, addressed by the customer's externalId. Same body and response. Sending a new externalId in the body changes it (or null clears it) — after that, address the customer by the new value.

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.

All fields optional; omitted fields are left untouched.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/customers/ext/acme-42" \  -H "Content-Type: application/json" \  -d '{    "name": "Acme Inc",    "externalId": "acme-42",    "description": "AI meeting-notes startup — growth tier",    "email": "ops@acme.com",    "website": "https://acme.com",    "phone": "+1 415 555 0100",    "legalName": "Acme Incorporated",    "addressLine1": "500 Market Street",    "city": "San Francisco",    "state": "CA",    "country": "United States",    "pincode": "94105",    "taxId": "US-EIN 12-3456789",    "currencyCode": "USD"  }'
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "customer": {      "id": "cus_abc123",      "externalId": "acme-42",      "slug": "acme-inc",      "name": "Acme Inc",      "description": "AI meeting-notes startup — growth tier",      "email": "ops@acme.com",      "website": "https://acme.com",      "phone": "+1 415 555 0100",      "legalName": "Acme Incorporated",      "addressLine1": "500 Market Street",      "city": "San Francisco",      "state": "CA",      "country": "United States",      "pincode": "94105",      "taxId": "US-EIN 12-3456789",      "currencyCode": "USD",      "createdAt": "2026-07-01T09:30:00.000Z",      "updatedAt": "2026-07-18T11:12:00.000Z"    }  }}
{  "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": 409,  "statusDetail": {    "status": "ERROR",    "message": "Customer \"cus_abc123\" is archived."  },  "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 GET

Previous Page

Delete a customer DELETE

Next Page

externalId?|

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
name?string
Length1 <= length <= 120
description?|
Lengthlength <= 500
email?string
Formatemail
Lengthlength <= 200
website?|
Lengthlength <= 200
phone?|
Lengthlength <= 40
legalName?|
Lengthlength <= 200
addressLine1?|
Lengthlength <= 200
city?|
Lengthlength <= 100
state?|
Lengthlength <= 100
country?|

Billing country. Decides which taxes (set up in Settings → Taxes) are charged on this customer's invoices and portal purchases; leave it empty for no tax.

Lengthlength <= 100
pincode?|
Lengthlength <= 20
taxId?|
Lengthlength <= 60
currencyCode?string

ISO 4217 code; must be enabled for the organisation. Defaults to the organisation's primary currency (USD if none is set) when omitted on create.

Length3 <= length <= 3
externalId?|

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
name?string
Length1 <= length <= 120
description?|
Lengthlength <= 500
email?string
Formatemail
Lengthlength <= 200
website?|
Lengthlength <= 200
phone?|
Lengthlength <= 40
legalName?|
Lengthlength <= 200
addressLine1?|
Lengthlength <= 200
city?|
Lengthlength <= 100
state?|
Lengthlength <= 100
country?|

Billing country. Decides which taxes (set up in Settings → Taxes) are charged on this customer's invoices and portal purchases; leave it empty for no tax.

Lengthlength <= 100
pincode?|
Lengthlength <= 20
taxId?|
Lengthlength <= 60
currencyCode?string

ISO 4217 code; must be enabled for the organisation. Defaults to the organisation's primary currency (USD if none is set) when omitted on create.

Length3 <= length <= 3