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

payment.succeeded POSTpayment.failed POST

Customer Portal

Mint a customer-portal access token POST
Payment

payment.succeeded

Triggered when money arrives — an invoice is paid, or the customer buys something in the customer portal.

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
  1. body
  1. body
  2. …
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

Always payment.succeeded.

triggered_at*string

When the event was triggered (ISO 8601).

Formatdate-time
data*

The customer, the payment, and the invoice or the portal item it paid for.

Response Body

Answer any 2xx within 5 seconds; the body is ignored. Anything else counts as failed and is retried.

Example Requests
POST/payment.succeeded
Request Body
application/json
{  "id": "evt_4869ad0e4916fba0fedcc0f651361755",  "event_type": "payment.succeeded",  "triggered_at": "2026-11-03T13:48:09.705Z",  "data": {    "customer": {      "id": "cus_abc123",      "name": "Acme Corp"    },    "payment": {      "number": "PAY-0012",      "amount": 118,      "currency_code": "usd",      "display_amount": 118,      "display_currency_code": "usd",      "method": "STRIPE",      "reference": "pi_3P0abc",      "automatic": true,      "paid_at": "2026-11-03T13:48:09.000Z"    },    "invoice": {      "id": "inv_def456",      "number": "INV-0042"    },    "item": null  }}
Header Parameters
{  "X-Clocknext-Signature": "t=1791367200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd",  "X-Clocknext-Event-Id": "evt_4869ad0e4916fba0fedcc0f651361755",  "X-Clocknext-Event-Type": "payment.succeeded"}

Types

Every object type on this page, with its fields.

PaymentSucceededEvent

FieldTypeRequiredDescription
idstringyesevt_ + 32 hex characters. Unique per event, and the same on every retry of it — use it to skip duplicates.
event_typestringyesAlways payment.succeeded.
triggered_atstringyesWhen the event was triggered (ISO 8601).
dataPaymentSucceededDatayesThe customer, the payment, and the invoice or the portal item it paid for.

PaymentSucceededData

The data of payment.succeeded: the customer, the payment and what it paid for. Exactly one of invoice (an invoice was paid) and item (a portal purchase) is set.

FieldTypeRequiredDescription
customerWebhookCustomeryesThe customer the event is about.
paymentobjectyesThe money that arrived.
invoiceWebhookInvoiceRef | nullyesThe invoice that was paid. Null for a portal buy.
itemobject | nullyesWhat the customer bought in the portal. Null for an invoice payment.

WebhookCustomer

The customer the event is about.

FieldTypeRequiredDescription
idstringyesThe customer's Clocknext id.
namestringyesThe customer's name.

PaymentSucceededData.payment

The money that arrived.

FieldTypeRequiredDescription
numberstring | nullyesThe payment's number.
amountnumberyesThe amount paid, in USD.
currency_codestringyesAlways usd — amount is in USD.
display_amountnumberyesThe same as amount, in USD (Clocknext converts no money).
display_currency_codestringyesAlways usd.
methodstring | nullyesSTRIPE or PADDLE for a gateway, or the method recorded by hand, such as BANK_TRANSFER.
referencestring | nullyesThe payment gateway's id for the payment, or the reference typed with a payment recorded by hand.
automaticbooleanyesTrue when a saved card was charged automatically for the invoice.
paid_atstring | nullyesWhen it was paid (ISO 8601).

WebhookInvoiceRef

The invoice the payment is for.

FieldTypeRequiredDescription
idstringyesThe invoice's id.
numberstringyesThe invoice's number.

PaymentSucceededData.item

FieldTypeRequiredDescription
type"wallet" | "credit" | "outcome" | "unit"yesWhat was bought.
namestringyesThe credit, outcome or unit bought, or Wallet top-up.
quantitynumber | nullyesHow many were bought. Null for a wallet top-up.

invoice.voided POST

Triggered when an invoice is voided, by hand or automatically.

payment.failed POST

Triggered when an automatic card charge for an invoice is refused — declined, or the bank asks the customer to confirm it.