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

Packages

Extra entitlements for one price, added to a customer's subscription. A package renews with the subscription on its plan's billing cycle until it is removed, and is always paid in advance. It has no billing cycle, billing mode or rollover of its own, never holds a wallet, and holds one flat fee at most. Each entitlement but a flat fee must be on the customer's plan as advance. Nothing is deleted — archive instead. Add and remove packages with the Subscriptions routes. See Packages.

List packages

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

GET
/packages

Lists your packages, oldest first. Pass active=true for the ones that can be added to a subscription.

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Query Parameters

active?boolean

true returns only active packages.

Response Body

Packages.

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 workspace's packages.

Example Request
curl -X GET 'https://payments.clocknext.com/api/v1/packages?active=true'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "packages": [      {        "id": "cmwi3bd3s00008dm6ogh2wkc4",        "name": "Chat Booster",        "description": "1,000 extra chat credits every billing cycle",        "cost": 4.5,        "currencyCode": "USD",        "isActive": true,        "entitlements": {          "credits": [            {              "id": "csmwfugghy00000006",              "name": "Chat Credits",              "quantity": 1000            }          ],          "outcomes": [],          "units": [],          "composites": [],          "flatFee": 2        },        "createdAt": "2026-11-15T17:10:05.080Z",        "updatedAt": "2026-11-15T17:10:05.903Z"      },      {        "id": "cmwi3bi7w000g8dm63vdvyhnt",        "name": "Image Booster",        "description": null,        "cost": 4.75,        "currencyCode": "USD",        "isActive": true,        "entitlements": {          "credits": [            {              "id": "csmwfugghy00000008",              "name": "Image Credits",              "quantity": 100            }          ],          "outcomes": [],          "units": [],          "composites": [],          "flatFee": null        },        "createdAt": "2026-11-15T17:10:11.708Z",        "updatedAt": "2026-11-15T17:10:11.708Z"      }    ]  }}

Create a package

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

POST
/packages

Creates a package: entitlements grouped by kind and its price (cost), paid in advance on the plan's billing cycle. Each entitlement but the flat fee must be on a customer's plan, as advance, before the package can be added.

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Request Body

application/json
  1. body
  1. body
  2. …

A new package with at least one entitlement. billingCycle, billingMode, rollover, currencyCode, isActive, subtotalUsd and priceAdjustment are a 400.

name*string

The package's name. Must be unique in the workspace (409 if taken).

Length1 <= length <= 120
description?|

Optional note about the package.

Lengthlength <= 500
cost*number

The package price per billing cycle of the plan, in USD.

Range0 <= value
entitlements*

The package's entitlements, grouped by kind.

Response Body

Package created.

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 new package.

curl -X POST 'https://payments.clocknext.com/api/v1/packages' \  -H 'Content-Type: application/json' \  -d '{  "name": "Chat Booster",  "description": "1,000 extra chat credits each cycle",  "cost": 5,  "entitlements": {    "credits": [      {        "id": "csmwfugghy00000006",        "quantity": 1000      }    ],    "flatFee": 2  }}'
Example Response
{  "statusCode": 201,  "statusDetail": {    "status": "SUCCESS",    "message": "Package created."  },  "result": {    "created": true,    "package": {      "id": "cmwi3bd3s00008dm6ogh2wkc4",      "name": "Chat Booster",      "description": "1,000 extra chat credits each cycle",      "cost": 5,      "currencyCode": "USD",      "isActive": true,      "entitlements": {        "credits": [          {            "id": "csmwfugghy00000006",            "name": "Chat Credits",            "quantity": 1000          }        ],        "outcomes": [],        "units": [],        "composites": [],        "flatFee": 2      },      "createdAt": "2026-11-15T17:10:05.080Z",      "updatedAt": "2026-11-15T17:10:05.080Z"    }  }}

Update a package

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

PATCH
/packages/{id}

Updates only the fields you send. entitlements is the complete new set; a group left out is empty. Without cost, new entitlements set the price to their list prices. Customers who have the package keep their copy.

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

Package id.

Request Body

application/json
  1. body
  1. body
  2. …

Only the fields you send change. entitlements is the complete new set. Without cost, new entitlements set the price to their list prices; an update without entitlements keeps the price. Customers who have the package keep their copy.

name?string

A new name. Must be unique in the workspace (409 if taken).

Length1 <= length <= 120
description?|

A new note. Send null to clear it.

Lengthlength <= 500
cost?number

A new price per billing cycle, in USD.

Range0 <= value
entitlements?

The complete new set of entitlements, grouped by kind.

Response Body

Package updated.

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 updated package.

curl -X PATCH 'https://payments.clocknext.com/api/v1/packages/cmwi3bd3s00008dm6ogh2wkc4' \  -H 'Content-Type: application/json' \  -d '{  "description": "1,000 extra chat credits every billing cycle"}'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Package updated."  },  "result": {    "updated": true,    "package": {      "id": "cmwi3bd3s00008dm6ogh2wkc4",      "name": "Chat Booster",      "description": "1,000 extra chat credits every billing cycle",      "cost": 5,      "currencyCode": "USD",      "isActive": true,      "entitlements": {        "credits": [          {            "id": "csmwfugghy00000006",            "name": "Chat Credits",            "quantity": 1000          }        ],        "outcomes": [],        "units": [],        "composites": [],        "flatFee": 2      },      "createdAt": "2026-11-15T17:10:05.080Z",      "updatedAt": "2026-11-15T17:10:05.860Z"    }  }}

Get a package

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

GET
/packages/{id}

Gets one package.

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

Package id.

Response Body

The package.

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 package with this id, in package.

Example Request
curl -X GET 'https://payments.clocknext.com/api/v1/packages/cmwi3bd3s00008dm6ogh2wkc4'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "package": {      "id": "cmwi3bd3s00008dm6ogh2wkc4",      "name": "Chat Booster",      "description": "1,000 extra chat credits each cycle",      "cost": 5,      "currencyCode": "USD",      "isActive": true,      "entitlements": {        "credits": [          {            "id": "csmwfugghy00000006",            "name": "Chat Credits",            "quantity": 1000          }        ],        "outcomes": [],        "units": [],        "composites": [],        "flatFee": 2      },      "createdAt": "2026-11-15T17:10:05.080Z",      "updatedAt": "2026-11-15T17:10:05.080Z"    }  }}

Archive a package

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

POST
/packages/{id}/archive

Archives a package: it can't be added to a subscription any more. Customers who have it keep it. Nothing is deleted.

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

Package id.

Response Body

Package archived.

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 archived package.

Example Request
curl -X POST 'https://payments.clocknext.com/api/v1/packages/cmwi3bd3s00008dm6ogh2wkc4/archive'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Package archived."  },  "result": {    "archived": true,    "package": {      "id": "cmwi3bd3s00008dm6ogh2wkc4",      "name": "Chat Booster",      "description": "1,000 extra chat credits every billing cycle",      "cost": 4.5,      "currencyCode": "USD",      "isActive": false,      "entitlements": {        "credits": [          {            "id": "csmwfugghy00000006",            "name": "Chat Credits",            "quantity": 1000          }        ],        "outcomes": [],        "units": [],        "composites": [],        "flatFee": 2      },      "createdAt": "2026-11-15T17:10:05.080Z",      "updatedAt": "2026-11-15T17:10:06.584Z"    }  }}

Unarchive a package

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

POST
/packages/{id}/unarchive

Restores an archived package: it can be added to subscriptions again.

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

Package id.

Response Body

Package unarchived.

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 restored package.

Example Request
curl -X POST 'https://payments.clocknext.com/api/v1/packages/cmwi3bd3s00008dm6ogh2wkc4/unarchive'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Package restored."  },  "result": {    "unarchived": true,    "package": {      "id": "cmwi3bd3s00008dm6ogh2wkc4",      "name": "Chat Booster",      "description": "1,000 extra chat credits every billing cycle",      "cost": 4.5,      "currencyCode": "USD",      "isActive": true,      "entitlements": {        "credits": [          {            "id": "csmwfugghy00000006",            "name": "Chat Credits",            "quantity": 1000          }        ],        "outcomes": [],        "units": [],        "composites": [],        "flatFee": 2      },      "createdAt": "2026-11-15T17:10:05.080Z",      "updatedAt": "2026-11-15T17:10:07.259Z"    }  }}

Types

Every object type on this page, with its fields.

Package

Entitlements and one price, added to a customer's subscription. It renews on the plan's billing cycle until removed, and is always paid in advance.

FieldTypeRequiredDescription
idstringyesThe package's id.
namestringyesThe package's name. Unique in the workspace.
descriptionstring | nullyesOptional note about the package. null when not set.
costnumberyesThe package price for each billing cycle of the plan, in USD.
currencyCodestringyesAlways USD.
isActivebooleanyesfalse once archived: it can't be added to a subscription. Read-only: use archive and unarchive.
entitlementsPackageEntitlementsyesWhat the package grants each cycle, grouped by kind.
createdAtstringyesWhen the package was created.
updatedAtstringyesWhen the package was last changed.

PackageEntitlements

What a package grants each cycle, grouped by kind. Every group is always present: an empty list, and flatFee null when there is none.

FieldTypeRequiredDescription
creditsPackageEntitlementItem[]yesThe credits and their quantities.
outcomesPackageEntitlementItem[]yesThe outcomes and their quantities.
unitsPackageEntitlementItem[]yesThe units and their quantities.
compositesPackageEntitlementItem[]yesThe composites and their quantities.
flatFeenumber | nullyesThe flat fee in USD, charged each cycle. null when there is none.

PackageEntitlementItem

One credit, outcome, unit or composite of a package, with the quantity it grants each cycle.

FieldTypeRequiredDescription
idstringyesThe credit's, outcome's, unit's or composite's own id.
namestringyesIts name.
quantityintegeryesHow many it grants each cycle.

CreatePackageInput

A new package with at least one entitlement. billingCycle, billingMode, rollover, currencyCode, isActive, subtotalUsd and priceAdjustment are a 400.

FieldTypeRequiredDescription
namestringyesThe package's name. Must be unique in the workspace (409 if taken).
descriptionstring | nullnoOptional note about the package.
costnumberyesThe package price per billing cycle of the plan, in USD.
entitlementsPackageEntitlementsInputyesThe package's entitlements, grouped by kind.

PackageEntitlementsInput

The package's entitlements, grouped by kind. A group left out is empty; each item appears once. wallet, the old flat list, and billingMode or rollover on an item are a 400.

FieldTypeRequiredDescription
creditsPackageEntitlementItemInput[]noThe credits, as { id, quantity }.
outcomesPackageEntitlementItemInput[]noThe outcomes, as { id, quantity }.
unitsPackageEntitlementItemInput[]noThe units, as { id, quantity }.
compositesPackageEntitlementItemInput[]noThe composites, as { id, quantity }.
flatFeenumber | nullnoA flat fee in USD each cycle. Left out or null, none.

PackageEntitlementItemInput

One credit, outcome, unit or composite to put in a package.

FieldTypeRequiredDescription
idstringyesThe credit's, outcome's, unit's or composite's own id. Active and in your workspace.
quantityintegeryesGranted each cycle, a whole number above 0.
namestringnoIgnored, so an item from a GET can be sent back as it is.

UpdatePackageInput

Only the fields you send change. entitlements is the complete new set. Without cost, new entitlements set the price to their list prices; an update without entitlements keeps the price. Customers who have the package keep their copy.

FieldTypeRequiredDescription
namestringnoA new name. Must be unique in the workspace (409 if taken).
descriptionstring | nullnoA new note. Send null to clear it.
costnumbernoA new price per billing cycle, in USD.
entitlementsPackageEntitlementsInputnoThe complete new set of entitlements, grouped by kind.

Plans

Plans customers subscribe to. Nothing is deleted — archive instead.

Credits

Credits your product draws down by `agentKey`, priced from a model bundle. Nothing is deleted — archive instead.