API Reference
Overview
The Clocknext Payments REST API — meter usage, manage customers and plans, and read billing from your own servers.
The Clocknext Payments API is a RESTful API your backend calls to meter LLM usage, manage customers and their plans, and read invoices and payments. Every endpoint lives under a single base URL, is authenticated with an organisation-scoped API key, and returns the same predictable response envelope.
Try it as you read
Every endpoint page in the API reference below is generated straight from the OpenAPI spec and ships with a live Try it playground plus cURL and Node.js code samples — so you can send a real request without leaving the page.
Base URL
https://payments.clocknext.com/api/v1All paths in this reference are relative to that base URL. So POST /usage
means POST https://payments.clocknext.com/api/v1/usage.
Authentication
Every request carries a per-organisation API key as a bearer token:
Authorization: Bearer cnk_your_key_hereKeys are created in Settings → API Keys and are scoped to the organisation that created them — a key can only ever read or write its own organisation's data. See Settings → API Keys for how to create, send, and rotate keys.
The shape of every response
Success or error, every response has the same envelope:
{
"statusCode": 200,
"statusDetail": { "status": "SUCCESS", "message": "OK" },
"result": { }
}statusCode mirrors the HTTP status, statusDetail.status is SUCCESS on a
2xx (ERROR otherwise), and your payload rides in result. Read the full
contract in The response envelope.
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.
The response envelope
The one response shape every endpoint returns.
Errors
Every status code the API returns and how to handle it.
Pagination
Page through list endpoints with limit and cursor.
What you can do with the API
| Area | Endpoints | What it's for |
|---|---|---|
| Usage | /usage | Record one metered LLM request and read a customer's usage. |
| Customers | /customers | Create, read, update, and delete customers; read balances and plan. |
| Members | /customers/{id}/members | Manage the people who belong to a customer. |
| Billing | Purchases · Invoices · Payments | Subscribe customers, read invoices, and mint hosted pay links. |
| Customer Portal | /portal/token | Mint 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.