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

Update a customer's card

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

POST
/customers/{id}/update-payment

Returns a link the customer opens to add or replace the card auto-pay charges. They enter the card on a secure page with your organisation's Stripe or Paddle form; nothing is charged there. The new card replaces the saved one, and any open auto-pay invoice on the customer's active plan is charged to it right away. The link is valid for 24 hours and works once; making a new link turns the older ones off. With returnUrl, the customer is sent there once the card is saved; otherwise they see a "Card saved" page. mode is update when the customer has a saved card, else add. 422 when no payment gateway is connected. When your Clocknext plan does not include Payments, every call is 403 FEATURE_LOCKED.

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

Customer id.

Request Body

application/json
  1. body
  1. body
  2. …
returnUrl?string

Where to send the customer once the card is saved: an absolute http(s) address, e.g. your billing page. Optional.

Formaturi

Response Body

Link made.

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 link and when it stops working.

curl -X POST 'https://payments.clocknext.com/api/v1/customers/cus_abc123/update-payment' \  -H 'Content-Type: application/json' \  -d '{  "returnUrl": "https://app.northwindtraders.com/billing"}'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "url": "https://payments.clocknext.com/card/Y21nN3E4ZjJ3MDAwMDN4c2YAAAADAWkFcCwk3JdQ8vX2mNp7LwYtR4sHg?return=https%3A%2F%2Fapp.northwindtraders.com%2Fbilling",    "expiresAt": "2026-10-28T10:00:00.000Z",    "mode": "update",    "gateway": "stripe"  }}

Update a customer's card using external Id

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

POST
/customers/ext/{externalId}/update-payment

The same call, addressed by the customer's externalId. Same body 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

Request Body

application/json
  1. body
  1. body
  2. …
returnUrl?string

Where to send the customer once the card is saved: an absolute http(s) address, e.g. your billing page. Optional.

Formaturi

Response Body

Link made.

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 link and when it stops working.

curl -X POST 'https://payments.clocknext.com/api/v1/customers/ext/string/update-payment' \  -H 'Content-Type: application/json' \  -d '{  "returnUrl": "https://app.northwindtraders.com/billing"}'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "url": "https://payments.clocknext.com/card/Y21nN3E4ZjJ3MDAwMDN4c2YAAAAEAWkFcCwq8LmN2pR5tW7vY1zA3cE4fG?return=https%3A%2F%2Fapp.northwindtraders.com%2Fbilling",    "expiresAt": "2026-10-28T10:00:00.000Z",    "mode": "add",    "gateway": "paddle"  }}

Types

Every object type on this page, with its fields.

UpdatePaymentInput

FieldTypeRequiredDescription
returnUrlstringnoWhere to send the customer once the card is saved: an absolute http(s) address, e.g. your billing page. Optional.

PaymentUpdateLink

FieldTypeRequiredDescription
urlstringyesThe secure card page (/card/<token>), with ?return= when a returnUrl was given. Send it to the customer or open it from your app.
expiresAtstringyesWhen the link stops working (24 hours after it was made).
mode"add" | "update"yesupdate when the customer has a saved card, else add.
gateway"stripe" | "paddle"yesThe organisation's payment gateway.

Change a recurring grant PUT

Previous Page

Get a customer's invoice balance GET

Next Page