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

credit_note.created POSTcredit_note.voided POST

Customer Portal

Mint a customer-portal access token POST
Credit note

credit_note.voided

Triggered when a credit note is voided while its invoice is still open. The invoice owes the amount again, and invoice.credit_notes_amount no longer counts the note.

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 credit_note.voided.

triggered_at*string

When the event was triggered (ISO 8601).

Formatdate-time
data*

The customer, the voided credit note and its invoice.

Response Body

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

Example Requests
POST/credit_note.voided
Request Body
application/json
{  "id": "evt_7d1c657dc3c2aec509c2719ba5908c9d",  "event_type": "credit_note.voided",  "triggered_at": "2026-11-16T10:05:00.000Z",  "data": {    "customer": {      "id": "cus_9",      "name": "Acme"    },    "credit_note": {      "id": "cn_1",      "number": "CN-007",      "status": "VOID",      "destination": "REFUND_TO_CARD",      "reason_code": "DUPLICATE_CHARGE",      "reason": "Duplicate charge",      "memo": null,      "subtotal": 100,      "tax_amount": 18,      "amount": 118,      "currency_code": "usd",      "created_at": "2026-11-16T09:20:01.000Z",      "voided_at": "2026-11-16T10:05:00.000Z"    },    "invoice": {      "id": "inv_42",      "number": "INV-0042",      "subscription_id": "pur_9",      "amount": 118,      "credit_notes_amount": 0    }  }}
Header Parameters
{  "X-Clocknext-Signature": "t=1791367200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd",  "X-Clocknext-Event-Id": "evt_7d1c657dc3c2aec509c2719ba5908c9d",  "X-Clocknext-Event-Type": "credit_note.voided"}

Types

Every object type on this page, with its fields.

CreditNoteVoidedEvent

FieldTypeRequiredDescription
idstringyesevt_ + 32 hex characters. Unique per event, and the same on every retry of it — use it to skip duplicates.
event_typestringyesAlways credit_note.voided.
triggered_atstringyesWhen the event was triggered (ISO 8601).
dataCreditNoteEventDatayesThe customer, the voided credit note and its invoice.

CreditNoteEventData

The data object of a credit_note.created or credit_note.voided event: the customer, the credit note and its invoice, as they are after the change.

FieldTypeRequiredDescription
customerWebhookCustomeryesThe customer the event is about.
credit_noteWebhookCreditNoteyesThe credit note when the event is triggered.
invoiceWebhookCreditNoteInvoiceyesThe invoice the credit note lowers.

WebhookCustomer

The customer the event is about.

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

WebhookCreditNote

A credit note: a document that lowers an invoice, in full or in part. All amounts are in USD. New values can be added to status, destination and reason_code.

FieldTypeRequiredDescription
idstringyesThe credit note's id.
numberstringyesThe credit note's number.
status"ISSUED" | "VOID"yesISSUED in credit_note.created, VOID in credit_note.voided.
destination"REDUCE_OPEN_INVOICE" | "CREDIT_TO_INVOICE_BALANCE" | "REFUND_TO_CARD"yesWhere the amount goes: off the open invoice, to the invoice balance, or back to the card.
reason_code"DUPLICATE_CHARGE" | "FRAUDULENT_CHARGE" | "ORDER_CHANGED" | "PRODUCT_UNSATISFACTORY" | "PLAN_CHANGE_UNUSED_TIME" | "SUBSCRIPTION_CANCELLED_UNUSED_TIME"yesWhy the credit note was made. The last 2 are the notes of a plan change and a cancel.
reasonstringyesThe label of reason_code, for example Duplicate charge.
memostring | nullyesThe extra text. Null when no memo was given.
subtotalnumberyesThe amount before tax, in USD.
tax_amountnumberyesThe tax given back, in USD. 0 when the invoice has no tax.
amountnumberyesThe total, in USD — subtotal plus tax_amount.
currency_codestringyesAlways usd — the amounts are in USD.
created_atstringyesWhen the credit note was issued (ISO 8601).
voided_atstring | nullyesWhen the credit note was voided (ISO 8601). Null in credit_note.created.

WebhookCreditNoteInvoice

The invoice of a credit note. When credit_notes_amount equals amount, the invoice is credited in full. That does not mean the money is on the card: for that, wait for refund.succeeded.

FieldTypeRequiredDescription
idstringyesThe invoice's id.
numberstringyesThe invoice's number.
subscription_idstring | nullyesThe subscription's purchase id. Null when the invoice belongs to no subscription.
amountnumberyesThe invoice total in USD, tax included, as issued. A credit note never changes it.
credit_notes_amountnumberyesThe total of the invoice's ISSUED credit notes, in USD, this one included. Void notes don't count.

credit_note.created POST

Triggered when a credit note is issued on an invoice: by hand, through the API, by a cancel with a refund, or by a plan change. When `invoice.credit_notes_amount` equals `invoice.amount`, the invoice is credited in full.

refund.created POST

Triggered when a card refund is asked of the payment gateway, for a credit note or from the invoice balance. The money is not on the card yet: wait for `refund.succeeded`. A refund split over 2 card payments triggers 2 events.