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

Create a credit note

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.

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

POST
/credit-notes

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Request Body

application/json
  1. body
  1. body
  2. …
invoiceId*string

The invoice to credit. It must be OPEN or PAID.

subtotalUsd*number

USD before tax; the invoice's tax is given back in proportion.

Range0 < value
reasonCode*string

Why you are making it.

Value in"DUPLICATE_CHARGE""FRAUDULENT_CHARGE""ORDER_CHANGED""PRODUCT_UNSATISFACTORY"
memo?string

A note for your records.

Lengthlength <= 1000
destination?string

Defaults to REDUCE_OPEN_INVOICE on an OPEN invoice. A PAID one needs a destination.

Value in"REDUCE_OPEN_INVOICE""CREDIT_TO_INVOICE_BALANCE""REFUND_TO_CARD"
idempotencyKey?string

1–200 characters. A repeat with the same key and body replays the first note.

Length1 <= length <= 200

Response Body

The same key made this note before; nothing new was made.

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.

curl -X POST 'https://payments.clocknext.com/api/v1/credit-notes' \  -H 'Content-Type: application/json' \  -d '{  "invoiceId": "cmvgvkpvy004m08l2iy0qdnc6",  "subtotalUsd": 200,  "reasonCode": "ORDER_CHANGED",  "memo": "One seat dropped",  "idempotencyKey": "cn-inv0005-seat"}'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Credit note already created."  },  "result": {    "creditNote": {      "id": "cmvgwc1xt000a08l5k2q9b7dn",      "creditNoteNumber": "CN-001",      "invoiceId": "cmvgvkpvy004m08l2iy0qdnc6",      "invoiceNumber": "INV-0005",      "customerId": "cmvgv9650000407iigjb3lt2p",      "customerName": "Adventure Works",      "destination": "REDUCE_OPEN_INVOICE",      "status": "ISSUED",      "reasonCode": "ORDER_CHANGED",      "reasonLabel": "Order changed",      "memo": "One seat dropped",      "subtotalUsd": 200,      "taxUsd": 0,      "totalUsd": 200,      "currencyCode": "USD",      "taxes": [],      "createdAt": "2026-10-28T09:12:44.000Z",      "createdBy": {        "id": "cmvg5kq3a0000a08l1z8c4t2m",        "name": "Dana Lee"      },      "voidedAt": null,      "refund": null    },    "invoice": {      "id": "cmvgvkpvy004m08l2iy0qdnc6",      "invoiceNumber": "INV-0005",      "status": "OPEN",      "amount": 2400,      "creditedUsd": 200,      "balanceAppliedUsd": 0,      "amountDueUsd": 2200    },    "replayed": true,    "refund": null  }}

Types

Every object type on this page, with its fields.

CreateCreditNoteInput

FieldTypeRequiredDescription
invoiceIdstringyesThe invoice to credit. It must be OPEN or PAID.
subtotalUsdnumberyesUSD before tax; the invoice's tax is given back in proportion.
reasonCodeCreateCreditNoteReasonCodeyesWhy you are making it.
memostringnoA note for your records.
destinationCreditNoteDestinationnoDefaults to REDUCE_OPEN_INVOICE on an OPEN invoice. A PAID one needs a destination.
idempotencyKeystringno1–200 characters. A repeat with the same key and body replays the first note.

CreateCreditNoteInput.reasonCode

The reasons you can give when you create a credit note.

CreateCreditNoteInput.destination

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

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.

InvoiceCreditSummary

An invoice as a write that changed it shows it: what is owed after the credit note or the void.

FieldTypeRequiredDescription
idstringyesThe invoice's id.
invoiceNumberstringyesIts reference.
statusInvoiceStatusyesIts status. PAID when a credit note settled it.
amountnumberyesThe invoice total in USD, tax included.
creditedUsdnumberyesAll credit notes on it, in USD, tax included.
balanceAppliedUsdnumberyesWhat the customer's invoice balance paid, in USD.
amountDueUsdnumberyesWhat is still owed, in USD. 0 unless it is OPEN.

InvoiceCreditSummary.status

OPEN: not paid yet. PAID: paid. VOID: voided. AUTO_CLOSED: a recurring invoice closed by "Auto close invoices on recurring"; applied as paid, with no payment collected.

Refund

Money going back to a customer's card.

FieldTypeRequiredDescription
idstringyesThe refund's id.
invoiceIdstringyesThe invoice whose payment it goes back to.
invoiceNumberstringyesThat invoice's reference.
customerIdstringyesThe customer.
creditNoteIdstring | nullyesThe credit note it came from. null for a refund of the invoice balance.
gateway"STRIPE" | "PADDLE"yesThe payment gateway that holds the money.
gatewayRefundIdstring | nullyesThe gateway's own id. null until the gateway answers.
amountUsdnumberyesUSD taken out of the invoice balance for it.
chargedAmountMinorinteger | nullyesWhat goes back to the card, in the smallest unit of the charged currency. null until known.
chargedCurrencyCodestring | nullyesThe currency that was charged. null until known.
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 a FAILED or REJECTED_IN_GATEWAY_REVIEW refund did not go through.
reasonstring | nullyesThe reason you gave. null when none.
createdAtstringyesWhen it was requested.
settledAtstring | nullyesWhen the gateway finished. null while pending.

List credit notes GET

Newest first, paged with `limit` (at most 50) and `cursor` → `nextCursor` — see [Paginating results](/docs/api-reference/pagination). Filter by `invoiceId` and/or `customerId`. Any other query parameter is a `400`.

Get a credit note GET

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