ClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Good to know

Response formatHandling errorsPaginating resultsSending data reliablyYour own customer idsWebhooks

API reference

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POST
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 PUTGet a customer's current plan GETChange a recurring grant PUTList Customer Usage Log GETLook Up Usage Logs by ID GET
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
List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE
PlansCreditsOutcomesUnitsComposites
List taxes GETCreate a tax POSTGet a tax GETUpdate a tax PATCH
List purchases GETCreate a purchase POSTGet a purchase GETUpdate a purchase's auto-payment setting PATCHCancel a purchase POST
List invoices GETGet an invoice GETMint a hosted pay link GET
List payments GETGet a payment GET
wallet.balance.update POSTwallet.balance.drop POST
Mint a customer-portal access token POST
Webhooks

wallet.balance.update

Triggered when a customer's Wallet balance increases or decreases. High volume: every usage charge on the Wallet triggers it too.

Header Parameters

X-Clocknext-Signature*string

t=<unix seconds>,v1=<hex HMAC-SHA256> — the HMAC of ${t}.${rawBody} keyed with the endpoint's signing secret. See Verify the signature.

X-Clocknext-Event-Id*string

The event's id — the same as id in the body, and the same on every retry.

X-Clocknext-Event-Type*string

The event name — the same as event_type in the body.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

{  "id": "evt_8c1e4b7a2f9d3e6c5b0a1f2e3d4c5b6a",  "event_type": "wallet.balance.update",  "triggered_at": "2026-10-07T09:30:12.418Z",  "data": {    "customer": {      "id": "cus_abc123",      "name": "Acme Corp"    },    "source": "TOPUP",    "previous_balance": 25,    "current_balance": 125,    "currency_code": "usd"  }}
{  "id": "evt_5d2a9e7c1b4f8a3d6e0c2b9a7f1e4d8c",  "event_type": "wallet.balance.update",  "triggered_at": "2026-10-07T11:14:05.207Z",  "data": {    "customer": {      "id": "cus_abc123",      "name": "Acme Corp"    },    "source": "USAGE",    "previous_balance": 125,    "current_balance": 124.25,    "currency_code": "usd"  }}
Content-Type: application/jsonX-Clocknext-Signature: t=1791367200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdX-Clocknext-Event-Id: <the payload's id>X-Clocknext-Event-Type: wallet.balance.update

Get a payment GET

Resolves only PAID invoices; anything else is a 404.

wallet.balance.drop POST

Triggered when a customer's Wallet balance falls to or below their low-balance alert level, or the endpoint's threshold if they have none.

id*string

evt_ + 32 hex characters. Unique per event, and the same on every retry of it — use it to skip duplicates.

event_type*string
triggered_at*string

When the event was triggered (ISO 8601).

Formatdate-time
data*