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

Get a credit note

One credit note, with the tax it gave back per tax rate.

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

GET
/credit-notes/{id}

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

Credit note id.

Response Body

The credit note.

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/credit-notes/cmvgwc1xt000a08l5k2q9b7dn'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "creditNote": {      "id": "cmvgwc9mq000b08l5n4w7e3hs",      "creditNoteNumber": "CN-002",      "invoiceId": "cmvgvkn14002u08l2ct47s2a7",      "invoiceNumber": "INV-0001",      "customerId": "cmvgva5po000c07iir1vtn8vl",      "customerName": "Northwind Traders",      "destination": "CREDIT_TO_INVOICE_BALANCE",      "status": "ISSUED",      "reasonCode": "DUPLICATE_CHARGE",      "reasonLabel": "Duplicate charge",      "memo": null,      "subtotalUsd": 100,      "taxUsd": 18,      "totalUsd": 118,      "currencyCode": "USD",      "taxes": [        {          "name": "GST",          "percentage": 18,          "behavior": "EXCLUSIVE",          "taxableAmountUsd": 100,          "amountUsd": 18        }      ],      "createdAt": "2026-10-28T09:18:02.000Z",      "createdBy": {        "id": "cmvg5kq3a0000a08l1z8c4t2m",        "name": "Dana Lee"      },      "voidedAt": null,      "refund": null    }  }}

Types

Every object type on this page, with its fields.

CreditNote

A document that lowers an invoice, in full or in part.

FieldTypeRequiredDescription
idstringyesThe credit note's id.
creditNoteNumberstringyesIts reference, such as CN-001. One sequence per workspace.
invoiceIdstringyesThe invoice it lowers.
invoiceNumberstringyesThat invoice's reference.
customerIdstringyesThe customer of the invoice.
customerNamestringyesThe customer's name.
destinationCreditNoteDestinationyesWhat it did with its amount.
status"ISSUED" | "VOID"yesISSUED, or VOID when it was cancelled while its invoice was open.
reasonCodeCreditNoteReasonCodeyesWhy it was made.
reasonLabelstringyesThe reason in words, such as Order changed.
memostring | nullyesYour note on it. null when none.
subtotalUsdnumberyesThe amount before tax, in USD.
taxUsdnumberyesThe tax given back, in USD.
totalUsdnumberyesThe total in USD: subtotalUsd plus taxUsd.
currencyCodestringyesUSD for every invoice issued since Clocknext stopped converting money (every invoice and charge is USD). An older invoice keeps the customer's currency it was issued with.
taxesCreditNoteTax[]yesThe tax given back, per tax rate.
createdAtstringyesWhen it was made.
createdByobject | nullyesWho made it. null for a note the system made.
voidedAtstring | nullyesWhen it was voided. null while issued.
refundobject | nullyesThe card refund this note asked for. null when there is none.

CreditNote.destination

What a credit note does with its amount. An OPEN invoice takes REDUCE_OPEN_INVOICE; a PAID one takes the other two.

CreditNote.reasonCode

Why a credit note was made. PLAN_CHANGE_UNUSED_TIME is the note a plan change makes itself; SUBSCRIPTION_CANCELLED_UNUSED_TIME is the note a cancel makes when it refunds the unused time. New values can be added: handle one you don't know.

CreditNoteTax

The part of a credit note's tax that one tax rate gave back.

FieldTypeRequiredDescription
namestringyesThe tax's name, saved on the invoice.
percentagenumberyesThe tax rate in percent.
behavior"INCLUSIVE" | "EXCLUSIVE"yesINCLUSIVE: already inside the price. EXCLUSIVE: added on top.
taxableAmountUsdnumberyesUSD this credit's tax was worked out on.
amountUsdnumberyesThe tax given back, in USD.

CreditNote.createdBy

The person or key owner who made it.

FieldTypeRequiredDescription
idstringyesTheir id.
namestringyesTheir name.

CreditNote.refund

The card refund behind the note.

FieldTypeRequiredDescription
idstringyesThe refund's id.
status"PENDING_AT_GATEWAY" | "SUCCEEDED" | "FAILED" | "REJECTED_IN_GATEWAY_REVIEW"yesPENDING_AT_GATEWAY until the gateway finishes. A failed or rejected refund returns the money.
failureReasonstring | nullyesWhy it failed, if it did. null otherwise.

Create a credit note POST

Lowers an invoice by `subtotalUsd`, before tax. An `OPEN` invoice owes less, and is paid when nothing is left. A `PAID` invoice needs a `destination`: `CREDIT_TO_INVOICE_BALANCE` or `REFUND_TO_CARD`. Answers the note and the invoice it changed. Send an `idempotencyKey` to retry safely.

Void a credit note POST

Cancels a credit note while its invoice is still `OPEN`: the invoice owes the amount again. Once the invoice is paid it can't be voided, nor can a note that gave money back. A voided note answers `CREDIT_NOTE_ALREADY_VOID`. Answers the note and the invoice.