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

List raw signals

Deprecated. Use List raw signals on events.clocknext.com; @clocknext/sdk 0.20 and later already do. Your organization's signals with their status, newest first, 50 a page, for the last 30 days.

Deprecated

Base URL https://payments.clocknext.com/api/v1

GET
/signal/list

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Query Parameters

customerId?string

Only this customer's signals. If externalId is sent too, customerId wins. An unknown id is not an error: the list is empty.

externalId?string

Only the signals of the customer with this externalId (1–32 letters, numbers or "-", matched exactly), and the signals sent with it that named no customer.

Match^[A-Za-z0-9-]{1,64}$
Length1 <= length <= 64
status?string

Only signals with this status. One value.

Value in"SUCCESS""PENDING""REJECTED"
type?string

Only signals of this type, in any case. OUTCOME gives a run's steps and its completion; COMPOSITE the composite completions.

Value in"WALLET""CREDIT""UNIT""OUTCOME""COMPOSITE"
from?string

First day to include, YYYY-MM-DD (UTC). The whole day is included. Omit it to start 30 days before the end of to, or 30 days before now.

Formatdate
to?string

Last day to include, YYYY-MM-DD (UTC). The whole day is included. Omit it for no end. Must not be before from.

Formatdate
cursor?string

Id to page after — the last id of the previous page.

Response Body

A page of signals, newest first.

application/json
  1. response
  1. response
  2. …
statusCode*integer

The HTTP status code of the response, repeated in the body.

statusDetail*

The status of the request. status is SUCCESS, and message says what happened.

result*

The data of the answer.

Example Request
curl -X GET 'https://payments.clocknext.com/api/v1/signal/list?customerId=cus_abc123&status=PENDING&type=CREDIT&from=2026-10-01&to=2026-10-07&cursor=cus_zzz789'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Signals loaded."  },  "result": {    "signals": [      {        "id": "01a15a16-01d4-761e-baec-dbe7f088c96c",        "createdAt": "2026-10-20T16:12:34.132Z",        "status": "SUCCESS",        "type": "UNIT",        "payload": {          "customerId": "cmvgva5po000c07iir1vtn8vl",          "idempotencyKey": "chat:nw:req_2001",          "agentKey": "pdf_export"        }      },      {        "id": "01a15a15-ff39-734c-957c-d0387537a318",        "createdAt": "2026-10-20T16:12:33.465Z",        "status": "SUCCESS",        "type": "CREDIT",        "payload": {          "customerId": "cmvgva5po000c07iir1vtn8vl",          "member": "priya.raman@northwindtraders.com",          "idempotencyKey": "chat:nw:req_2001",          "usage": {            "model": "gpt-4o-mini",            "inputTokens": 2000,            "outputTokens": 500,            "cacheTokens": 0,            "cacheWriteTokens": 0          },          "agentKey": "chat_message"        }      },      {        "id": "01a15a15-d708-7784-a954-24cad1d90e00",        "createdAt": "2026-10-20T16:12:23.176Z",        "status": "SUCCESS",        "type": "OUTCOME_COMPLETION",        "payload": {          "customerId": "cmvgva5po000c07iir1vtn8vl",          "runId": "TCK-48299",          "agentKey": "support_ticket"        }      },      {        "id": "01a15a15-ccec-758e-ad47-1f18e965ad90",        "createdAt": "2026-10-20T16:12:20.588Z",        "status": "PENDING",        "type": "CREDIT",        "payload": {          "externalId": "tailspin-org",          "usage": {            "model": "claude-sonnet-4-5",            "inputTokens": 100,            "outputTokens": 10,            "cacheTokens": 0,            "cacheWriteTokens": 0          },          "agentKey": "deep_research",          "customerId": "cmvgv9ebb000707iipffdxzwj"        },        "error": {          "type": "user_error",          "message": "Credit \"Deep Research\" is not part of this customer's plan, and no composite covering it is sold on this plan either."        },        "attempts": 2      },      {        "id": "01a15a15-c461-71f0-938e-3d34dbb1ed56",        "createdAt": "2026-10-20T16:12:18.401Z",        "status": "SUCCESS",        "type": "WALLET",        "payload": {          "externalId": "fabrikam-org",          "usage": {            "model": "gemini-2.5-flash",            "inputTokens": 40000,            "outputTokens": 8000,            "cacheTokens": 0,            "cacheWriteTokens": 0          },          "customerId": "cmvgv9dyg000607ii9z6oghzf"        }      },      {        "id": "01a15a15-bbc5-77a0-9dff-faa6f09479de",        "createdAt": "2026-10-20T16:12:16.197Z",        "status": "SUCCESS",        "type": "OUTCOME",        "payload": {          "externalId": "contoso-org",          "usage": {            "model": "claude-haiku-4-5",            "inputTokens": 2800,            "outputTokens": 600,            "cacheTokens": 0,            "cacheWriteTokens": 0          },          "agentKey": "support_ticket.triage",          "runId": "CT-9001",          "customerId": "cmvgv9th0000a07iisl2s8u6q"        }      },      {        "id": "01a15a15-b773-70e3-ad71-87994218bda2",        "createdAt": "2026-10-20T16:12:15.091Z",        "status": "SUCCESS",        "type": "COMPOSITE",        "payload": {          "customerId": "cmvgva5po000c07iir1vtn8vl",          "composite": {            "research_report": "RPT-2026-Q4-EV"          }        }      },      {        "id": "01a15a15-d5ce-73e2-9ed0-cfd2fb08fd0c",        "createdAt": "2026-10-20T16:12:22.862Z",        "status": "SUCCESS",        "type": "UNIT",        "payload": {          "customerId": "cmvgva5po000c07iir1vtn8vl",          "agentKey": "pdf_export"        }      }    ],    "nextCursor": "eyJ0cyI6I…redacted"  }}

Types

Every object type on this page, with its fields.

SignalListEntry

FieldTypeRequiredDescription
idstringyesThe signal id.
createdAtstringyesWhen the API received the signal.
status"SUCCESS" | "PENDING" | "REJECTED"yesSUCCESS: counted. PENDING: not counted yet, can be retried. REJECTED: given up, never counted.
type"WALLET" | "CREDIT" | "OUTCOME" | "OUTCOME_COMPLETION" | "UNIT" | "COMPOSITE" | nullyesThe route used. OUTCOME is a step, OUTCOME_COMPLETION a completion. null when unreadable.
payloadobject | nullyesThe request as stored: unknown keys dropped, defaults filled, customerId added. null when unreadable.
errorobjectnoOnly on PENDING and REJECTED rows: why, and its type.
attemptsintegernoPENDING and REJECTED rows only: how many times the signal was processed.

SignalListEntry.error

Only on PENDING and REJECTED rows: why, and its type.

FieldTypeRequiredDescription
type"user_error" | "validation_error" | "server_error" | "not_yet" | nullyesuser_error (fix the request), not_yet (may pass later), server_error or validation_error.
messagestringyesWhat went wrong, in words.

Complete composite POST

Deprecated. Use [Complete composite](/docs/api-reference/signals/eventsCompleteCompositeSignal) on `events.clocknext.com`; `@clocknext/sdk` 0.20 and later already do. Closes one occurrence of a composite and bills it once. Answers `202`; a signal that can't be processed stays `PENDING`.

Retry signals POST

Deprecated. Use [Retry signals](/docs/api-reference/signals/eventsRetrySignals) on `events.clocknext.com`; `@clocknext/sdk` 0.20 and later already do. Sends 1 to 50 `PENDING` signals again. A signal gets 11 attempts, then becomes `REJECTED`.