Get a credit note
One credit note, with the tax it gave back per tax rate.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringCredit note id.
The credit note.
application/json- response
statusCode*integerThe 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 GET 'https://payments.clocknext.com/api/v1/credit-notes/cmvgwc1xt000a08l5k2q9b7dn'{ "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.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The credit note's id. |
creditNoteNumber | string | yes | Its reference, such as CN-001. One sequence per workspace. |
invoiceId | string | yes | The invoice it lowers. |
invoiceNumber | string | yes | That invoice's reference. |
customerId | string | yes | The customer of the invoice. |
customerName | string | yes | The customer's name. |
destination | CreditNoteDestination | yes | What it did with its amount. |
status | "ISSUED" | "VOID" | yes | ISSUED, or VOID when it was cancelled while its invoice was open. |
reasonCode | CreditNoteReasonCode | yes | Why it was made. |
reasonLabel | string | yes | The reason in words, such as Order changed. |
memo | string | null | yes | Your note on it. null when none. |
subtotalUsd | number | yes | The amount before tax, in USD. |
taxUsd | number | yes | The tax given back, in USD. |
totalUsd | number | yes | The total in USD: subtotalUsd plus taxUsd. |
currencyCode | string | yes | USD 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. |
taxes | CreditNoteTax[] | yes | The tax given back, per tax rate. |
createdAt | string | yes | When it was made. |
createdBy | object | null | yes | Who made it. null for a note the system made. |
voidedAt | string | null | yes | When it was voided. null while issued. |
refund | object | null | yes | The 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.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The tax's name, saved on the invoice. |
percentage | number | yes | The tax rate in percent. |
behavior | "INCLUSIVE" | "EXCLUSIVE" | yes | INCLUSIVE: already inside the price. EXCLUSIVE: added on top. |
taxableAmountUsd | number | yes | USD this credit's tax was worked out on. |
amountUsd | number | yes | The tax given back, in USD. |
CreditNote.createdBy
The person or key owner who made it.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Their id. |
name | string | yes | Their name. |
CreditNote.refund
The card refund behind the note.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The refund's id. |
status | "PENDING_AT_GATEWAY" | "SUCCEEDED" | "FAILED" | "REJECTED_IN_GATEWAY_REVIEW" | yes | PENDING_AT_GATEWAY until the gateway finishes. A failed or rejected refund returns the money. |
failureReason | string | null | yes | Why 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.