Base URL https://payments.clocknext.com/api/v1
The customer's invoice balance and one page of its ledger, newest first. It is credit we owe them from credit notes, plan changes and adjustments, and it pays their invoices. Not the wallet. Paged with limit and cursor.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringCustomer id.
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.
The balance and a page of its ledger.
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/customers/cus_abc123/invoice-balance?limit=50&cursor=cus_zzz789'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "result": { "balance": { "totalUsd": 140, "refundableToCardUsd": 100, "invoicesOnlyUsd": 40 }, "entries": [ { "id": "cmvgwe3tn000g08l5u2c5v8jd", "type": "CREDIT_MANUAL_ADJUSTMENT", "origin": "NO_CARD_PAYMENT_INVOICES_ONLY", "amountUsd": 40, "balanceAfterUsd": 140, "note": "Goodwill for the 12 Oct outage", "createdAt": "2026-10-27T15:02:10.000Z", "createdBy": { "id": "cmvg5kq3a0000a08l1z8c4t2m", "name": "Dana Lee" }, "creditNote": null, "refund": null, "appliedInvoice": null, "sourceInvoice": null }, { "id": "cmvgwe1qa000f08l5x7b2m4kt", "type": "CREDIT_FROM_CREDIT_NOTE", "origin": "CARD_PAYMENT_REFUNDABLE_TO_CARD", "amountUsd": 100, "balanceAfterUsd": 100, "note": null, "createdAt": "2026-10-26T11:40:05.000Z", "createdBy": { "id": "cmvg5kq3a0000a08l1z8c4t2m", "name": "Dana Lee" }, "creditNote": { "id": "cmvgwc9mq000b08l5n4w7e3hs", "creditNoteNumber": "CN-002", "reasonCode": "DUPLICATE_CHARGE", "invoice": { "id": "cmvgvkn14002u08l2ct47s2a7", "invoiceNumber": "INV-0001" } }, "refund": null, "appliedInvoice": null, "sourceInvoice": { "id": "cmvgvkn14002u08l2ct47s2a7", "invoiceNumber": "INV-0001" } } ], "nextCursor": null }}Base URL https://payments.clocknext.com/api/v1
The same call, addressed by the customer's externalId. Same query and response.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
externalId*stringYour own id for the customer: 1–64 letters, numbers or "-". Case-sensitive.
^[A-Za-z0-9-]{1,64}$1 <= length <= 64limit?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.
The balance and a page of its ledger.
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/customers/ext/string/invoice-balance?limit=50&cursor=cus_zzz789'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "result": { "balance": { "totalUsd": 140, "refundableToCardUsd": 100, "invoicesOnlyUsd": 40 }, "entries": [ { "id": "cmvgwe3tn000g08l5u2c5v8jd", "type": "CREDIT_MANUAL_ADJUSTMENT", "origin": "NO_CARD_PAYMENT_INVOICES_ONLY", "amountUsd": 40, "balanceAfterUsd": 140, "note": "Goodwill for the 12 Oct outage", "createdAt": "2026-10-27T15:02:10.000Z", "createdBy": { "id": "cmvg5kq3a0000a08l1z8c4t2m", "name": "Dana Lee" }, "creditNote": null, "refund": null, "appliedInvoice": null, "sourceInvoice": null }, { "id": "cmvgwe1qa000f08l5x7b2m4kt", "type": "CREDIT_FROM_CREDIT_NOTE", "origin": "CARD_PAYMENT_REFUNDABLE_TO_CARD", "amountUsd": 100, "balanceAfterUsd": 100, "note": null, "createdAt": "2026-10-26T11:40:05.000Z", "createdBy": { "id": "cmvg5kq3a0000a08l1z8c4t2m", "name": "Dana Lee" }, "creditNote": { "id": "cmvgwc9mq000b08l5n4w7e3hs", "creditNoteNumber": "CN-002", "reasonCode": "DUPLICATE_CHARGE", "invoice": { "id": "cmvgvkn14002u08l2ct47s2a7", "invoiceNumber": "INV-0001" } }, "refund": null, "appliedInvoice": null, "sourceInvoice": { "id": "cmvgvkn14002u08l2ct47s2a7", "invoiceNumber": "INV-0001" } } ], "nextCursor": null }}Types
Every object type on this page, with its fields.
InvoiceBalance
Credit we owe a customer, which pays their invoices. Not the wallet.
| Field | Type | Required | Description |
|---|---|---|---|
totalUsd | number | yes | What the customer holds now, in USD. |
refundableToCardUsd | number | yes | The part a card paid: what a refund could send back to the card. |
invoicesOnlyUsd | number | yes | The part with no card behind it, such as goodwill. Only usable on invoices. |
InvoiceBalanceEntry
One line of a customer's invoice-balance ledger. A line is never edited; a new one corrects it.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The entry's id. |
type | "CREDIT_FROM_CREDIT_NOTE" | "CREDIT_FROM_PLAN_CHANGE_UNUSED_TIME" | "CREDIT_MANUAL_ADJUSTMENT" | "DEBIT_MANUAL_ADJUSTMENT" | "DEBIT_TO_PAY_INVOICE" | "CREDIT_FROM_VOIDED_INVOICE" | "DEBIT_FOR_CARD_REFUND" | "CREDIT_FROM_FAILED_CARD_REFUND" | yes | What a ledger line did. A CREDIT_ value adds to the balance; a DEBIT_ value takes from it. |
origin | "CARD_PAYMENT_REFUNDABLE_TO_CARD" | "NO_CARD_PAYMENT_INVOICES_ONLY" | null | yes | Whether a card payment is behind the money. null when not recorded. |
amountUsd | number | yes | Signed USD: a credit is positive, a debit negative. |
balanceAfterUsd | number | yes | What the customer's invoice balance was right after this line, in USD. |
note | string | null | yes | The note it was written with. null when none. |
createdAt | string | yes | When it was written. |
createdBy | object | null | yes | Who wrote it. null for a line the system wrote. |
creditNote | object | null | yes | The credit note this line belongs to. null when none. |
refund | object | null | yes | The refund this line belongs to. null when none. |
appliedInvoice | InvoiceRef | null | yes | The invoice this line paid or gave back. null when none. |
sourceInvoice | InvoiceRef | null | yes | The invoice a card credit came from. null when none. |
InvoiceBalanceEntry.createdBy
The person or key owner who wrote it.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Their id. |
name | string | yes | Their name. |
InvoiceBalanceEntry.creditNote
The credit note behind the line.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Its id. |
creditNoteNumber | string | null | yes | Its reference. |
reasonCode | "DUPLICATE_CHARGE" | "FRAUDULENT_CHARGE" | "ORDER_CHANGED" | "PRODUCT_UNSATISFACTORY" | "PLAN_CHANGE_UNUSED_TIME" | "SUBSCRIPTION_CANCELLED_UNUSED_TIME" | null | yes | Why it was made. |
invoice | InvoiceRef | null | yes | The invoice the note was made on. |
InvoiceRef
An invoice named by a ledger line.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The invoice's id. |
invoiceNumber | string | null | yes | Its reference. null when it has none. |
InvoiceBalanceEntry.refund
The refund behind the line.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Its id. |
status | "PENDING_AT_GATEWAY" | "SUCCEEDED" | "FAILED" | "REJECTED_IN_GATEWAY_REVIEW" | null | yes | Its status. |
failureReason | string | null | yes | Why it failed, if it did. |
invoice | InvoiceRef | null | yes | The invoice the refund is on. |