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
Entitlements and Plans

Plans

Plans customers subscribe to. Nothing is deleted — archive instead.

List plans in an organization

GET
/plans

Lists your plans, oldest first. Pass active=true for purchasable ones only.

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

Query Parameters

active?boolean

true returns only active (purchasable) plans.

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/plans?active=true"
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "plans": [      {        "id": "string",        "name": "string",        "description": "string",        "billingCycle": "MONTHLY",        "cost": 0,        "priceAdjustment": 0,        "walletFundedArrear": true,        "currencyCode": "string",        "isActive": true,        "createdAt": "2019-08-24T14:15:22Z",        "updatedAt": "2019-08-24T14:15:22Z",        "entitlements": [          {            "id": "string",            "type": "WALLET",            "billingMode": "ADVANCE",            "creditId": "string",            "outcomeId": "string",            "unitId": "string",            "compositeId": "string",            "targetName": "string",            "quantity": 0,            "amount": 0,            "rollover": false          }        ]      }    ]  }}
{  "statusCode": 401,  "statusDetail": {    "status": "ERROR",    "message": "Invalid API key."  },  "result": {}}
{  "statusCode": 500,  "statusDetail": {    "status": "ERROR",    "message": "Could not complete the request."  },  "result": {}}

Create a plan

POST
/plans

Creates a plan in your workspace's primary currency.

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

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

curl -X POST "https://example.com/plans" \  -H "Content-Type: application/json" \  -d '{    "name": "Pro",    "description": "For growing teams",    "billingCycle": "MONTHLY",    "entitlements": [      {        "type": "CREDIT",        "billingMode": "ADVANCE",        "creditId": "cr_8f2k1",        "quantity": 1000,        "rollover": true      },      {        "type": "OUTCOME",        "billingMode": "ARREAR",        "outcomeId": "oc_3n7p2"      },      {        "type": "PRICING_METRIC",        "billingMode": "ADVANCE",        "compositeId": "cmp_7d1x9",        "quantity": 50      },      {        "type": "WALLET",        "billingMode": "ADVANCE",        "amount": 25      }    ]  }'
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "created": true,    "plan": {      "id": "string",      "name": "string",      "description": "string",      "billingCycle": "MONTHLY",      "cost": 0,      "priceAdjustment": 0,      "walletFundedArrear": true,      "currencyCode": "string",      "isActive": true,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "entitlements": [        {          "id": "string",          "type": "WALLET",          "billingMode": "ADVANCE",          "creditId": "string",          "outcomeId": "string",          "unitId": "string",          "compositeId": "string",          "targetName": "string",          "quantity": 0,          "amount": 0,          "rollover": 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": 409,  "statusDetail": {    "status": "ERROR",    "message": "Customer \"cus_abc123\" is archived."  },  "result": {}}
{  "statusCode": 500,  "statusDetail": {    "status": "ERROR",    "message": "Could not complete the request."  },  "result": {}}

Update a plan

PATCH
/plans/{id}

Updates only the fields you send. Changes apply to new purchases.

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

Path Parameters

id*string

Plan id.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Any create fields.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/plans/pl_2h6m3" \  -H "Content-Type: application/json" \  -d '{    "name": "Pro Monthly"  }'
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "updated": true,    "plan": {      "id": "string",      "name": "string",      "description": "string",      "billingCycle": "MONTHLY",      "cost": 0,      "priceAdjustment": 0,      "walletFundedArrear": true,      "currencyCode": "string",      "isActive": true,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "entitlements": [        {          "id": "string",          "type": "WALLET",          "billingMode": "ADVANCE",          "creditId": "string",          "outcomeId": "string",          "unitId": "string",          "compositeId": "string",          "targetName": "string",          "quantity": 0,          "amount": 0,          "rollover": 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": 409,  "statusDetail": {    "status": "ERROR",    "message": "Customer \"cus_abc123\" is archived."  },  "result": {}}
{  "statusCode": 500,  "statusDetail": {    "status": "ERROR",    "message": "Could not complete the request."  },  "result": {}}

Get a plan

GET
/plans/{id}

Gets one plan.

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

Path Parameters

id*string

Plan id.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/plans/pl_2h6m3"
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "plan": {      "id": "string",      "name": "string",      "description": "string",      "billingCycle": "MONTHLY",      "cost": 0,      "priceAdjustment": 0,      "walletFundedArrear": true,      "currencyCode": "string",      "isActive": true,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "entitlements": [        {          "id": "string",          "type": "WALLET",          "billingMode": "ADVANCE",          "creditId": "string",          "outcomeId": "string",          "unitId": "string",          "compositeId": "string",          "targetName": "string",          "quantity": 0,          "amount": 0,          "rollover": false        }      ]    }  }}
{  "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": {}}

Archive a plan

POST
/plans/{id}/archive

Archives a plan. Nothing is deleted.

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

Path Parameters

id*string

Plan id.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/plans/pl_2h6m3/archive"
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "archived": true,    "plan": {      "id": "string",      "name": "string",      "description": "string",      "billingCycle": "MONTHLY",      "cost": 0,      "priceAdjustment": 0,      "walletFundedArrear": true,      "currencyCode": "string",      "isActive": true,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "entitlements": [        {          "id": "string",          "type": "WALLET",          "billingMode": "ADVANCE",          "creditId": "string",          "outcomeId": "string",          "unitId": "string",          "compositeId": "string",          "targetName": "string",          "quantity": 0,          "amount": 0,          "rollover": false        }      ]    }  }}
{  "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": {}}

Unarchive a plan

POST
/plans/{id}/unarchive

Restores an archived plan.

Authorization

apiKey
AuthorizationBearer <token>

Organisation-scoped key from Settings → API Keys.

In: header

Path Parameters

id*string

Plan id.

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/plans/pl_2h6m3/unarchive"
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "OK"  },  "result": {    "unarchived": true,    "plan": {      "id": "string",      "name": "string",      "description": "string",      "billingCycle": "MONTHLY",      "cost": 0,      "priceAdjustment": 0,      "walletFundedArrear": true,      "currencyCode": "string",      "isActive": true,      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z",      "entitlements": [        {          "id": "string",          "type": "WALLET",          "billingMode": "ADVANCE",          "creditId": "string",          "outcomeId": "string",          "unitId": "string",          "compositeId": "string",          "targetName": "string",          "quantity": 0,          "amount": 0,          "rollover": false        }      ]    }  }}
{  "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": {}}

Remove a member DELETE

Previous Page

Credits

Credits your product draws down by `agentKey`, priced from a model bundle. Nothing is deleted — archive instead.

name*string
Length1 <= length <= 120
description?|
Lengthlength <= 500
billingCycle*BillingCycle

Value in

  • "MONTHLY"
  • "QUARTERLY"
  • "SEMI_ANNUAL"
  • "YEARLY"
  • "FREE"
walletFundedArrear?boolean

Pay ARREAR usage from the wallet.

Defaultfalse
priceAdjustment?number

Rounding adjustment (USD).

Default0
entitlements*array<>
Items1 <= items
name?string
Length1 <= length <= 120
description?|
Lengthlength <= 500
billingCycle?BillingCycle

Value in

  • "MONTHLY"
  • "QUARTERLY"
  • "SEMI_ANNUAL"
  • "YEARLY"
  • "FREE"
walletFundedArrear?boolean
priceAdjustment?number
entitlements?array<>
Items1 <= items