API Reference
Quickstart
Create a customer and record your first usage signal end to end — in under ten minutes.
This guide takes you from an API key to a priced usage signal in four steps. By the end you'll have created a customer and recorded a metered LLM request against it. Every step shows both cURL and Node.js.
You'll need
An API key (cnk_…) from Settings → API Keys. Keep it in an environment
variable — the samples below read $CLOCKNEXT_API_KEY. The Node.js tabs use
the official @clocknext/sdk client (cnk); install it
with npm install @clocknext/sdk.
Set your key
Export your key so every request can read it. Never hard-code it in source you commit.
export CLOCKNEXT_API_KEY="cnk_your_key_here"Create a customer
A customer is who you bill. Only name and email are required — everything
else is an optional profile field you can also fill in later. Here we send the
full profile so invoices render complete from day one.
curl https://payments.clocknext.com/api/v1/customers \
-H "Authorization: Bearer $CLOCKNEXT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Inc",
"email": "ops@acme.com",
"description": "AI meeting-notes startup — growth tier",
"website": "https://acme.com",
"phone": "+1 415 555 0100",
"legalName": "Acme Incorporated",
"addressLine1": "500 Market Street",
"addressLine2": "Suite 400",
"city": "San Francisco",
"state": "CA",
"country": "United States",
"pincode": "94105",
"taxId": "US-EIN 12-3456789",
"notes": "Design partner — invoices reviewed by finance before send",
"currencyCode": "USD",
"creditAllowance": 10000
}'import { ClockNext } from "@clocknext/sdk";
const cnk = new ClockNext({ apiKey: process.env.CLOCKNEXT_API_KEY! });
const customer = await cnk.customers.create({
name: "Acme Inc",
email: "ops@acme.com",
description: "AI meeting-notes startup — growth tier",
website: "https://acme.com",
phone: "+1 415 555 0100",
legalName: "Acme Incorporated",
addressLine1: "500 Market Street",
addressLine2: "Suite 400",
city: "San Francisco",
state: "CA",
country: "United States",
pincode: "94105",
taxId: "US-EIN 12-3456789",
notes: "Design partner — invoices reviewed by finance before send",
currencyCode: "USD",
creditAllowance: 10000,
});
const customerId = customer.id; // e.g. "cus_abc123"Grab the new customer's id — you'll reference it as customerId everywhere
else. The SDK returns it directly; the raw response wraps it in the
envelope's result.
Record a usage signal
Meter one LLM request against that customer. Here we bill the customer's USD
wallet at the model's provider cost. Only customerId, type, model,
and the token counts do the pricing — member and custom are optional
attribution metadata, filled here so the usage log lands fully annotated.
curl https://payments.clocknext.com/api/v1/usage \
-H "Authorization: Bearer $CLOCKNEXT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cus_abc123",
"type": "wallet",
"model": "gpt-4o",
"member": "dana@acme.com",
"inputTokens": 1200,
"outputTokens": 350,
"cacheTokens": 200,
"custom": { "feature": "chat", "region": "eu" }
}'// bill the customer's USD wallet at the model's provider cost
await cnk.signals.wallet({
customerId: "cus_abc123",
model: "gpt-4o",
tokens: { input: 1200, output: 350, cache: 200 },
member: "dana@acme.com",
custom: { feature: "chat", region: "eu" },
});The platform prices the request server-side from the model's live rates and
returns the computed numbers in result. A caller can never post a price.
Read it back
Confirm the signal landed by listing the customer's recent usage.
curl "https://payments.clocknext.com/api/v1/usage?customerId=cus_abc123&limit=10" \
-H "Authorization: Bearer $CLOCKNEXT_API_KEY"// The SDK is write-only for usage; read logs back over the raw endpoint.
const res = await fetch(
"https://payments.clocknext.com/api/v1/usage?customerId=cus_abc123&limit=10",
{ headers: { Authorization: `Bearer ${process.env.CLOCKNEXT_API_KEY}` } },
);
const { result } = await res.json(); // { customer, totals, logs }What just happened
You authenticated with a bearer key, created a billing identity (the customer), metered one request against it, and read the result back — all through the same base URL and the same response envelope.