ClocknextClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Good to know

Response formatHandling errorsPaginating resultsSending data reliablyYour own customer idsWebhooks

API reference

Signals

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POSTList Customer Usage Log GETLook Up Usage Logs by ID GET

Deprecated

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POST

Customers

List customers GETCreate a customer POSTGet a customer GETUpdate a customer PATCHDelete a customer DELETEGet a customer's balances GETGet a customer's wallet ledger GETSet a customer's low-balance alert for wallet PUTGet a customer's current plan GETChange a recurring grant PUTUpdate a customer's card POSTGet a customer's invoice balance GETAdjust a customer's invoice balance POST

Deprecated

List Customer Usage Log GETLook Up Usage Logs by ID GET

Manage

Manage a customer's credit balance POSTManage a customer's outcome balance POSTManage a customer's unit balance POSTManage a customer's composite balance POSTManage a customer's wallet balance POST

Members

List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE

Plans and Entitlements

PlansPackagesCreditsOutcomesUnitsComposites

Taxes

List taxes GETCreate a tax POSTGet a tax GETUpdate a tax PATCH

Purchases

List purchases GETCreate a purchase POSTGet a purchase GETUpdate a purchase's auto-payment setting PATCHCancel a purchase POST

Checkout

Create a checkout POST

Subscriptions

List subscriptions GETGet a subscription GETCancel a subscription POSTAdd packages to a subscription POSTRemove a package from a subscription POST

Plan changes

List plan changes GETPreview a plan change POSTChange a customer's plan POSTGet a plan change GET

Invoices

List invoices GETGet an invoice GETMint a hosted pay link GETRecord a payment POST

Credit notes

List credit notes GETCreate a credit note POSTGet a credit note GETVoid a credit note POST

Refunds

List refunds GETRefund to the card POSTGet a refund GET

Payments

List payments GETGet a payment GET

Webhooks

Customer Portal

Mint a customer-portal access token POST

Get a customer's invoice balance using customer Id

Base URL https://payments.clocknext.com/api/v1

GET
/customers/{id}/invoice-balance

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.

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

Customer id.

Query Parameters

limit?integer

Rows 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.

Range1 <= value <= 50
Default50
cursor?string

Id to page after — the last id of the previous page.

Response Body

The balance and a page of its ledger.

application/json
  1. response
  1. response
  2. …
statusCode*integer

The 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.

Example Request
curl -X GET 'https://payments.clocknext.com/api/v1/customers/cus_abc123/invoice-balance?limit=50&cursor=cus_zzz789'
Example Response
{  "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  }}

Get a customer's invoice balance using external Id

Base URL https://payments.clocknext.com/api/v1

GET
/customers/ext/{externalId}/invoice-balance

The same call, addressed by the customer's externalId. Same query and response.

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

externalId*string

Your own id for the customer: 1–64 letters, numbers or "-". Case-sensitive.

Match^[A-Za-z0-9-]{1,64}$
Length1 <= length <= 64

Query Parameters

limit?integer

Rows 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.

Range1 <= value <= 50
Default50
cursor?string

Id to page after — the last id of the previous page.

Response Body

The balance and a page of its ledger.

application/json
  1. response
  1. response
  2. …
statusCode*integer

The 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.

Example Request
curl -X GET 'https://payments.clocknext.com/api/v1/customers/ext/string/invoice-balance?limit=50&cursor=cus_zzz789'
Example Response
{  "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.

FieldTypeRequiredDescription
totalUsdnumberyesWhat the customer holds now, in USD.
refundableToCardUsdnumberyesThe part a card paid: what a refund could send back to the card.
invoicesOnlyUsdnumberyesThe 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.

FieldTypeRequiredDescription
idstringyesThe 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"yesWhat 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" | nullyesWhether a card payment is behind the money. null when not recorded.
amountUsdnumberyesSigned USD: a credit is positive, a debit negative.
balanceAfterUsdnumberyesWhat the customer's invoice balance was right after this line, in USD.
notestring | nullyesThe note it was written with. null when none.
createdAtstringyesWhen it was written.
createdByobject | nullyesWho wrote it. null for a line the system wrote.
creditNoteobject | nullyesThe credit note this line belongs to. null when none.
refundobject | nullyesThe refund this line belongs to. null when none.
appliedInvoiceInvoiceRef | nullyesThe invoice this line paid or gave back. null when none.
sourceInvoiceInvoiceRef | nullyesThe invoice a card credit came from. null when none.

InvoiceBalanceEntry.createdBy

The person or key owner who wrote it.

FieldTypeRequiredDescription
idstringyesTheir id.
namestringyesTheir name.

InvoiceBalanceEntry.creditNote

The credit note behind the line.

FieldTypeRequiredDescription
idstringyesIts id.
creditNoteNumberstring | nullyesIts reference.
reasonCode"DUPLICATE_CHARGE" | "FRAUDULENT_CHARGE" | "ORDER_CHANGED" | "PRODUCT_UNSATISFACTORY" | "PLAN_CHANGE_UNUSED_TIME" | "SUBSCRIPTION_CANCELLED_UNUSED_TIME" | nullyesWhy it was made.
invoiceInvoiceRef | nullyesThe invoice the note was made on.

InvoiceRef

An invoice named by a ledger line.

FieldTypeRequiredDescription
idstringyesThe invoice's id.
invoiceNumberstring | nullyesIts reference. null when it has none.

InvoiceBalanceEntry.refund

The refund behind the line.

FieldTypeRequiredDescription
idstringyesIts id.
status"PENDING_AT_GATEWAY" | "SUCCEEDED" | "FAILED" | "REJECTED_IN_GATEWAY_REVIEW" | nullyesIts status.
failureReasonstring | nullyesWhy it failed, if it did.
invoiceInvoiceRef | nullyesThe invoice the refund is on.

Update a customer's card POST

Previous Page

Adjust a customer's invoice balance POST

Next Page