List credit notes
Newest first, paged with limit (at most 50) and cursor → nextCursor — see Paginating results. Filter by invoiceId and/or customerId. Any other query parameter is a 400.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
invoiceId?stringOnly the credit notes of this invoice.
customerId?stringRestrict results to this customer.
limit?integerRows on one page: default 50, maximum 50 (a bigger value is cut to 50). Zero, a negative number or a non-number is a 400.
1 <= value <= 5050cursor?stringId to page after — the last id of the previous page.
Credit notes.
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*One page of credit notes.
curl -X GET 'https://payments.clocknext.com/api/v1/credit-notes?invoiceId=cmvgvkn14002u08l2ct47s2a7&customerId=cus_abc123&limit=50&cursor=cus_zzz789'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "result": { "creditNotes": [ { "id": "cmvgwcf2k000c08l5y1d6u8ra", "creditNoteNumber": "CN-003", "invoiceId": "cmvgvkn14002u08l2ct47s2a7", "invoiceNumber": "INV-0001", "customerId": "cmvgva5po000c07iir1vtn8vl", "customerName": "Northwind Traders", "destination": "REFUND_TO_CARD", "status": "ISSUED", "reasonCode": "PRODUCT_UNSATISFACTORY", "reasonLabel": "Product unsatisfactory", "memo": "Report never arrived", "subtotalUsd": 50, "taxUsd": 0, "totalUsd": 50, "currencyCode": "USD", "taxes": [], "createdAt": "2026-10-28T09:25:30.000Z", "createdBy": { "id": "cmvg5kq3a0000a08l1z8c4t2m", "name": "Dana Lee" }, "voidedAt": null, "refund": { "id": "cmvgwd7rj000d08l5z6k9p1qb", "status": "PENDING_AT_GATEWAY", "failureReason": null } }, { "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 }, { "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 } ], "nextCursor": 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. |
Record a payment POST
Records a payment received outside Clocknext (bank transfer, cash, UPI, …) and marks an `OPEN` invoice `PAID`; any other status is a `409`. Paying the first invoice starts the purchase once its start date has come. No receipt email is sent. Stripe and Paddle payments come from the gateway only.
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.