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

Create a checkout

Returns a link (url, valid 24 hours) for a customer to buy a plan on a secure payment page, then sends them to returnUrl. Nothing changes until they pay. Act on the subscription.activated webhook, not the redirect. A plan with nothing to pay is switched at once (200, status: SWITCHED).

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

POST
/checkout

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Request Body

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

The customer, by Clocknext id. Or send externalId; if both are sent, customerId wins.

externalId?string

The customer, by your own id.

planId*string

The plan to buy. Any active plan.

returnUrl?string

Where to send the customer after paying: an absolute http(s) address, used as given. Optional.

Formaturi

Response Body

Nothing to pay — the plan was switched at once.

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 plan was switched at once; no link.

curl -X POST 'https://payments.clocknext.com/api/v1/checkout' \  -H 'Content-Type: application/json' \  -d '{  "customerId": "cmgcust0001",  "planId": "cmgplan0pro",  "returnUrl": "https://app.northwindtraders.com/billing"}'
Example Response
{  "statusCode": 201,  "statusDetail": {    "status": "SUCCESS",    "message": "Checkout created."  },  "result": {    "id": "cmhcheckout0001",    "url": "https://payments.clocknext.com/checkout/Y21oY2hlY2tvdXQwMDAxAbCdEfGhIjKlMnOpQrStUv",    "expiresAt": "2026-10-30T10:00:00.000Z"  }}

Types

Every object type on this page, with its fields.

CheckoutCreateInput

FieldTypeRequiredDescription
customerIdstringnoThe customer, by Clocknext id. Or send externalId; if both are sent, customerId wins.
externalIdstringnoThe customer, by your own id.
planIdstringyesThe plan to buy. Any active plan.
returnUrlstringnoWhere to send the customer after paying: an absolute http(s) address, used as given. Optional.

CheckoutSwitched

FieldTypeRequiredDescription
status"SWITCHED"yesThe plan had nothing to pay and no card to save, so it is already active.
purchaseIdstringyesThe new purchase.
planobjectyesThe plan the customer is on now.

CheckoutSwitched.plan

The plan the customer is on now.

FieldTypeRequiredDescription
idstringyesThe plan's id.
namestringyesThe plan's name.

Cancel a purchase POST

Cancels the purchase now: it becomes `CANCELLED`, its `OPEN` invoices are voided, and usage not billed yet gets a final invoice. This also completes a subscription marked for cancellation. A purchase already cancelled answers `200` again. To cancel at the period end, use [Cancel a subscription](/docs/api-reference/subscriptions/cancelSubscription).

List subscriptions GET

Your customers' subscriptions: one row per period, newest purchase first, the running period before the ones it renewed from. A subscription is addressed by its `purchaseId`. Paged by purchase with `limit` and `cursor`; see [Paginating results](/docs/api-reference/pagination).