Base URL https://payments.clocknext.com/api/v1
Adds to or takes from the customer's invoice balance: a positive delta adds, a negative one takes. It writes one ledger line; fix a mistake with a line the other way. Added money is cash, never refundable to a card. A debit can't take more than the balance holds.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringCustomer id.
application/json- body
delta*numberUSD, not zero. Positive adds cash or goodwill; negative takes, never more than the balance holds.
notes?stringWhy. Kept on the ledger line. At most 300 characters.
length <= 300idempotencyKey?string1–255 characters. A repeat with the same key and body adjusts nothing.
1 <= length <= 255Invoice balance adjusted.
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/customers/cus_abc123/invoice-balance/adjust' \ -H 'Content-Type: application/json' \ -d '{ "delta": 40, "notes": "Goodwill for the 12 Oct outage", "idempotencyKey": "goodwill-northwind-oct"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Invoice balance adjusted." }, "result": { "adjusted": true, "replayed": false, "adjustedAt": "2026-10-27T15:02:10.000Z", "remaining": 140, "balance": { "totalUsd": 140, "refundableToCardUsd": 100, "invoicesOnlyUsd": 40 }, "entry": { "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 }, "customerArchived": false }}Base URL https://payments.clocknext.com/api/v1
The same call, addressed by the customer's externalId. Same body 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 <= 64application/json- body
delta*numberUSD, not zero. Positive adds cash or goodwill; negative takes, never more than the balance holds.
notes?stringWhy. Kept on the ledger line. At most 300 characters.
length <= 300idempotencyKey?string1–255 characters. A repeat with the same key and body adjusts nothing.
1 <= length <= 255Invoice balance adjusted.
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/customers/ext/string/invoice-balance/adjust' \ -H 'Content-Type: application/json' \ -d '{ "delta": 40, "notes": "Goodwill for the 12 Oct outage", "idempotencyKey": "goodwill-northwind-oct"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Invoice balance adjusted." }, "result": { "adjusted": true, "replayed": false, "adjustedAt": "2026-10-27T15:02:10.000Z", "remaining": 140, "balance": { "totalUsd": 140, "refundableToCardUsd": 100, "invoicesOnlyUsd": 40 }, "entry": { "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 }, "customerArchived": false }}Types
Every object type on this page, with its fields.
AdjustInvoiceBalanceInput
| Field | Type | Required | Description |
|---|---|---|---|
delta | number | yes | USD, not zero. Positive adds cash or goodwill; negative takes, never more than the balance holds. |
notes | string | no | Why. Kept on the ledger line. At most 300 characters. |
idempotencyKey | string | no | 1–255 characters. A repeat with the same key and body adjusts nothing. |
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. |
Get a customer's invoice balance GET
Previous Page
List Customer Usage Log GET
Deprecated. Use [List Customer Usage Log](/docs/api-reference/signals/eventsListUsageLog) on `events.clocknext.com`; `@clocknext/sdk` 0.20 and later already do. One customer's usage (credit, outcome, unit, wallet and composite rows) in one feed, sorted by time. Paged with `limit` and `cursor`; narrow it with `from` and `to`.