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

Get a customer's wallet ledger using customer Id

GET
/customers/{id}/wallet

Both wallet balances, in USD, and the wallet ledger: every movement of wallet money, most recent first. source on each row says what caused it. On a USAGE_LOG row, usageLogId is the id of the matching row in List Customer Usage Log, so each charge links to the exact signal that caused it. Cursor-paginated: pass limit/cursor and read nextCursor back; null means the last page. Narrow by date with from/to. To top up or draw down the wallet, use Manage a customer's wallet balance.

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

Path Parameters

id*string

Customer id.

Query Parameters

limit?integer

Maximum rows to return. Must be a positive number; clamped to 1–200.

Range1 <= value <= 200
Default50
cursor?string

Opaque token from a previous response's nextCursor. Omit for the first page.

from?string

First day to include, YYYY-MM-DD (UTC). The whole day is included. Omit for no lower bound. Keep sending the same value while paging with cursor.

Formatdate
to?string

Last day to include, YYYY-MM-DD (UTC). The whole day is included. Omit for no upper bound. Must not be before from.

Formatdate

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/cus_abc123/wallet?limit=25&cursor=eyJ0cyI6IjIwMjYtMTAtMDlUMDU6Mjc6MjEuNjM3WiIsImlkIjoiY212MGl4NHgxMDAwMjA2andjZncyM2J2ZCJ9&from=2026-10-01&to=2026-10-07"
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "balanceUsd": 1.27665825,    "reservedBalanceUsd": null,    "lowBalanceAlertUsd": 1,    "transactions": [      {        "id": "cmv0ix4x1000206jwcfw23bvd",        "createdAt": "2026-10-09T05:27:21.637Z",        "type": "DEBIT",        "pool": "main",        "source": "USAGE_LOG",        "amount": 0.111189,        "amountUsd": 0.111189,        "currencyCode": "USD",        "currencyRateUsd": 1,        "notes": null,        "entitlementType": null,        "entitlementId": null,        "entitlementName": null,        "usageLogId": "cmv0ix4vi000106jw21pdf86i",        "purchaseId": null,        "purchaseNumber": null      },      {        "id": "cmuwsho1v000604l6v9xb1cz1",        "createdAt": "2026-10-06T14:44:11.395Z",        "type": "CREDIT",        "pool": "main",        "source": "RENEWAL",        "amount": 100,        "amountUsd": 100,        "currencyCode": "USD",        "currencyRateUsd": 1,        "notes": null,        "entitlementType": null,        "entitlementId": null,        "entitlementName": null,        "usageLogId": null,        "purchaseId": "cmuwr5z0k000004l9a1b2c3d4",        "purchaseNumber": "PUR-012"      },      {        "id": "cmuwr61jn000004l9n8n08ral",        "createdAt": "2026-10-06T14:07:09.395Z",        "type": "DEBIT",        "pool": "main",        "source": "API",        "amount": 10,        "amountUsd": 10,        "currencyCode": "USD",        "currencyRateUsd": 1,        "notes": "Correct a double-counted signal",        "entitlementType": null,        "entitlementId": null,        "entitlementName": null,        "usageLogId": null,        "purchaseId": null,        "purchaseNumber": null      }    ],    "nextCursor": null  }}
{  "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": 500,  "statusDetail": {    "status": "ERROR",    "message": "Could not complete the request."  },  "result": {}}

Get a customer's wallet ledger using external Id

GET
/customers/ext/{externalId}/wallet

The same call, addressed by the customer's externalId. Same query parameters 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

Query Parameters

limit?integer

Maximum rows to return. Must be a positive number; clamped to 1–200.

Range1 <= value <= 200
Default50
cursor?string

Opaque token from a previous response's nextCursor. Omit for the first page.

from?string

First day to include, YYYY-MM-DD (UTC). The whole day is included. Omit for no lower bound. Keep sending the same value while paging with cursor.

Formatdate
to?string

Last day to include, YYYY-MM-DD (UTC). The whole day is included. Omit for no upper bound. Must not be before from.

Formatdate

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/customers/ext/acme-42/wallet?limit=25&cursor=eyJ0cyI6IjIwMjYtMTAtMDlUMDU6Mjc6MjEuNjM3WiIsImlkIjoiY212MGl4NHgxMDAwMjA2andjZncyM2J2ZCJ9&from=2026-10-01&to=2026-10-07"
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "balanceUsd": 1.27665825,    "reservedBalanceUsd": null,    "lowBalanceAlertUsd": 1,    "transactions": [      {        "id": "cmv0ix4x1000206jwcfw23bvd",        "createdAt": "2026-10-09T05:27:21.637Z",        "type": "DEBIT",        "pool": "main",        "source": "USAGE_LOG",        "amount": 0.111189,        "amountUsd": 0.111189,        "currencyCode": "USD",        "currencyRateUsd": 1,        "notes": null,        "entitlementType": null,        "entitlementId": null,        "entitlementName": null,        "usageLogId": "cmv0ix4vi000106jw21pdf86i",        "purchaseId": null,        "purchaseNumber": null      },      {        "id": "cmuwsho1v000604l6v9xb1cz1",        "createdAt": "2026-10-06T14:44:11.395Z",        "type": "CREDIT",        "pool": "main",        "source": "RENEWAL",        "amount": 100,        "amountUsd": 100,        "currencyCode": "USD",        "currencyRateUsd": 1,        "notes": null,        "entitlementType": null,        "entitlementId": null,        "entitlementName": null,        "usageLogId": null,        "purchaseId": "cmuwr5z0k000004l9a1b2c3d4",        "purchaseNumber": "PUR-012"      },      {        "id": "cmuwr61jn000004l9n8n08ral",        "createdAt": "2026-10-06T14:07:09.395Z",        "type": "DEBIT",        "pool": "main",        "source": "API",        "amount": 10,        "amountUsd": 10,        "currencyCode": "USD",        "currencyRateUsd": 1,        "notes": "Correct a double-counted signal",        "entitlementType": null,        "entitlementId": null,        "entitlementName": null,        "usageLogId": null,        "purchaseId": null,        "purchaseNumber": null      }    ],    "nextCursor": null  }}
{  "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": 500,  "statusDetail": {    "status": "ERROR",    "message": "Could not complete the request."  },  "result": {}}

Get a customer's balances GET

Previous Page

Set a customer's low-balance alert PUT

Next Page