API Reference
Response format
Every endpoint — success or error — returns the same predictable envelope. Here's the contract.
Every response from the API, whether it succeeds or fails, has the same shape. Parse it once and reuse that logic everywhere.
{
"statusCode": 200,
"statusDetail": { "status": "SUCCESS", "message": "OK" },
"result": { }
}Fields
Prop
Type
On success
statusDetail.status is SUCCESS and the payload rides in result. For a list
endpoint result holds the rows (and paging info); for a single-record endpoint
it holds that record.
{
"statusCode": 201,
"statusDetail": { "status": "SUCCESS", "message": "Customer created" },
"result": { "id": "cus_abc123", "name": "Acme Inc", "email": "ops@acme.com" }
}On error
statusDetail.status is ERROR, result is always an empty object, and the
reason is in statusDetail.message. See Errors for the full
list of status codes.
{
"statusCode": 404,
"statusDetail": { "status": "ERROR", "message": "Customer not found" },
"result": {}
}Handling it in code
If you call the API directly, branch on the HTTP status (or equivalently on
statusDetail.status), read result on success, and surface
statusDetail.message on failure.
const res = await fetch("https://payments.clocknext.com/api/v1/customers", {
headers: { Authorization: `Bearer ${process.env.CLOCKNEXT_API_KEY}` },
});
const body = await res.json();
if (body.statusDetail.status !== "SUCCESS") {
throw new Error(`${body.statusCode}: ${body.statusDetail.message}`);
}
const customers = body.result;The official @clocknext/sdk client does this for you — every
method returns result directly and throws a typed error on failure, so you
never unwrap the envelope by hand:
const customers = await cnk.customers.list(); // already unwrapped