ClocknextClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Good to know

Response formatHandling errorsPaginating resultsSending data reliablyYour own customer idsWebhooks

API reference

Signals

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POSTList Customer Usage Log GETLook Up Usage Logs by ID GET

Deprecated

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POST

Customers

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 for wallet PUTGet a customer's current plan GETChange a recurring grant PUTUpdate a customer's card POSTGet a customer's invoice balance GETAdjust a customer's invoice balance POST

Deprecated

List Customer Usage Log GETLook Up Usage Logs by ID GET

Manage

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

Members

List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE

Plans and Entitlements

PlansPackagesCreditsOutcomesUnitsComposites

Taxes

List taxes GETCreate a tax POSTGet a tax GETUpdate a tax PATCH

Purchases

List purchases GETCreate a purchase POSTGet a purchase GETUpdate a purchase's auto-payment setting PATCHCancel a purchase POST

Checkout

Create a checkout POST

Subscriptions

List subscriptions GETGet a subscription GETCancel a subscription POSTAdd packages to a subscription POSTRemove a package from a subscription POST

Plan changes

List plan changes GETPreview a plan change POSTChange a customer's plan POSTGet a plan change GET

Invoices

List invoices GETGet an invoice GETMint a hosted pay link GETRecord a payment POST

Credit notes

List credit notes GETCreate a credit note POSTGet a credit note GETVoid a credit note POST

Refunds

List refunds GETRefund to the card POSTGet a refund GET

Payments

List payments GETGet a payment GET

Webhooks

Customer Portal

Mint a customer-portal access token POST

API Reference

Overview

The Clocknext Payments API and Node.js SDK — meter LLM usage, manage customers and plans.

Clocknext works through the Node.js SDK and API. Both meter LLM usage — against a credit, outcome, wallet, unit, or composite — and manage customers and their plans. Every request is authenticated with an organisation-scoped API key, and every response, from either the SDK or the API, follows the same response envelope.

Install the SDK

npm install @clocknext/sdk

The SDK is optional. You can call the API directly with cURL or your own HTTP client.

Base URLs

The API has two hosts. Each endpoint calls one of them, and its page shows the full URL. You cannot change the base URL of an endpoint.

HostBase URLEndpoints
Events APIhttps://events.clocknext.com/api/v1Record signals, list and retry signals, read the usage log
Payments APIhttps://payments.clocknext.com/api/v1Customers, balances, plans, purchases, invoices, payments and everything else

All paths in this reference are relative to the base URL of their host — POST /signal/credit calls POST https://events.clocknext.com/api/v1/signal/credit. The same signal and usage-log routes on payments.clocknext.com are deprecated. They still answer, but they will be removed.

Both hosts take the same API key and return the same response envelope.

OpenAPI specs

Each host has an OpenAPI 3.1 file. Use it to generate a client in any language.

HostOpenAPI file
Events API/openapi-events.yaml
Payments API/openapi.yaml

Each API page ends with a Types section. It gives a field table for every object type that the page uses, nested types included.

Authentication

Every request carries a per-organisation API key as a bearer token:

Authorization: Bearer cnk_your_key_here

Create, send, and rotate keys in Settings → API Keys.

The shape of every response

Success or error, every response has the same envelope:

{
  "statusCode": 200,
  "statusDetail": { "status": "SUCCESS", "message": "OK" },
  "result": { }
}

See Response format for the full contract.

Where to go next

Quickstart

Create a customer and record your first usage signal in under ten minutes.

API keys

Create an API key, send it, and rotate it safely.

Response format

The one response shape every endpoint returns.

Handling errors

Every status code the API returns and how to handle it.

Paginating results

Page through list endpoints with limit and cursor.

What you can do

AreaEndpointsWhat it's for
Signals/signal/*Record one metered request against a credit, outcome, wallet, or unit, and close a composite. List raw signals, retry the ones that could not be counted, and read the usage log. On events.clocknext.com.
Customers/customersCreate, read, update, and delete customers; read balances and plan.
Members/customers/{id}/membersManage the people who belong to a customer.
BillingPurchases · Packages · Plan changes · Invoices · Credit notes · Refunds · PaymentsSubscribe customers, add packages to their subscription, change their plan, read invoices, credit and refund them, and mint hosted pay links.
Customer Portal/portal/tokenMint short-lived tokens to embed the customer portal.

Server-side only

Your cnk_… key has organisation-wide read/write access. Call this API from a server, script, or job you control — never ship the key to a browser or mobile app. To give a customer access to their own data, mint a portal token instead.

Quickstart

Create a customer, package a Plan, and record your first usage signal — start to finish.

On this page

Install the SDKBase URLsOpenAPI specsAuthenticationThe shape of every responseWhere to go nextWhat you can do