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
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
application/json- body
invoiceId*stringThe invoice to credit. It must be OPEN or PAID.
subtotalUsd*numberUSD before tax; the invoice's tax is given back in proportion.
0 < valuereasonCode*stringWhy you are making it.
"DUPLICATE_CHARGE""FRAUDULENT_CHARGE""ORDER_CHANGED""PRODUCT_UNSATISFACTORY"memo?stringA note for your records.
length <= 1000destination?stringDefaults to REDUCE_OPEN_INVOICE on an OPEN invoice. A PAID one needs a destination.
"REDUCE_OPEN_INVOICE""CREDIT_TO_INVOICE_BALANCE""REFUND_TO_CARD"idempotencyKey?string1–200 characters. A repeat with the same key and body replays the first note.
1 <= length <= 200The same key made this note before; nothing new was made.
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 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"}'{ "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
| Field | Type | Required | Description |
|---|---|---|---|
invoiceId | string | yes | The invoice to credit. It must be OPEN or PAID. |
subtotalUsd | number | yes | USD before tax; the invoice's tax is given back in proportion. |
reasonCode | CreateCreditNoteReasonCode | yes | Why you are making it. |
memo | string | no | A note for your records. |
destination | CreditNoteDestination | no | Defaults to REDUCE_OPEN_INVOICE on an OPEN invoice. A PAID one needs a destination. |
idempotencyKey | string | no | 1–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.
| 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. |
InvoiceCreditSummary
An invoice as a write that changed it shows it: what is owed after the credit note or the void.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The invoice's id. |
invoiceNumber | string | yes | Its reference. |
status | InvoiceStatus | yes | Its status. PAID when a credit note settled it. |
amount | number | yes | The invoice total in USD, tax included. |
creditedUsd | number | yes | All credit notes on it, in USD, tax included. |
balanceAppliedUsd | number | yes | What the customer's invoice balance paid, in USD. |
amountDueUsd | number | yes | What 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.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The refund's id. |
invoiceId | string | yes | The invoice whose payment it goes back to. |
invoiceNumber | string | yes | That invoice's reference. |
customerId | string | yes | The customer. |
creditNoteId | string | null | yes | The credit note it came from. null for a refund of the invoice balance. |
gateway | "STRIPE" | "PADDLE" | yes | The payment gateway that holds the money. |
gatewayRefundId | string | null | yes | The gateway's own id. null until the gateway answers. |
amountUsd | number | yes | USD taken out of the invoice balance for it. |
chargedAmountMinor | integer | null | yes | What goes back to the card, in the smallest unit of the charged currency. null until known. |
chargedCurrencyCode | string | null | yes | The currency that was charged. null until known. |
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 a FAILED or REJECTED_IN_GATEWAY_REVIEW refund did not go through. |
reason | string | null | yes | The reason you gave. null when none. |
createdAt | string | yes | When it was requested. |
settledAt | string | null | yes | When 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.