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

package.added POSTpackage.removal_scheduled POSTpackage.ended POST

Customer Portal

Mint a customer-portal access token POST
Package

package.added

Triggered when a package on a subscription becomes active: its invoice is paid or recorded as paid. An unpaid attach is announced by invoice.created.

Header Parameters

X-Clocknext-Signature*string

t=<unix seconds>,v1=<hex HMAC-SHA256> — the HMAC of ${t}.${rawBody} keyed with the endpoint's signing secret. See Verify the signature.

X-Clocknext-Event-Id*string

The event's id — the same as id in the body, and the same on every retry.

X-Clocknext-Event-Type*string

The event name — the same as event_type in the body.

Request Body

application/json
  1. body
  1. body
  2. …
id*string

evt_ + 32 hex characters. Unique per event, and the same on every retry of it — use it to skip duplicates.

event_type*string

Always package.added.

triggered_at*string

When the event was triggered (ISO 8601).

Formatdate-time
data*

The customer, the subscription and the package, as it is after the change.

Response Body

Answer any 2xx within 5 seconds; the body is ignored. Anything else counts as failed and is retried.

Example Requests
POST/package.added
Request Body
application/json
{  "id": "evt_4c7a2e9f1b3d5a8c6e0f2b4d6a8c0e1f",  "event_type": "package.added",  "triggered_at": "2026-11-15T17:10:10.391Z",  "data": {    "customer": {      "id": "csmwfugghy0000002b",      "name": "Northwind Traders"    },    "subscription": {      "id": "cmwfwy4px000veqm6f12fgddc"    },    "package": {      "id": "cmwi3bgxx00088dm6svjsa3i1",      "package_id": "cmwi3bd3s00008dm6ogh2wkc4",      "name": "Chat Booster",      "status": "ACTIVE",      "cost": 4.5,      "entitlements": {        "credits": [          {            "id": "csmwfugghy00000006",            "name": "Chat Credits",            "quantity": 1000          }        ],        "outcomes": [],        "units": [],        "composites": [],        "flat_fee": 2      },      "started_at": "2026-11-15T17:10:10.174Z",      "ends_at": null,      "ended_at": null,      "ended_reason": null,      "cancel_reason": null,      "invoice_id": "cmwi3bgyj000b8dm6e9gshf1t"    }  }}
Header Parameters
{  "X-Clocknext-Signature": "t=1791367200,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd",  "X-Clocknext-Event-Id": "evt_4c7a2e9f1b3d5a8c6e0f2b4d6a8c0e1f",  "X-Clocknext-Event-Type": "package.added"}

Types

Every object type on this page, with its fields.

PackageAddedEvent

FieldTypeRequiredDescription
idstringyesevt_ + 32 hex characters. Unique per event, and the same on every retry of it — use it to skip duplicates.
event_typestringyesAlways package.added.
triggered_atstringyesWhen the event was triggered (ISO 8601).
dataPackageEventDatayesThe customer, the subscription and the package, as it is after the change.

PackageEventData

The data object of a package.added, package.removal_scheduled or package.ended event: the customer, the subscription and the package.

FieldTypeRequiredDescription
customerWebhookCustomeryesThe customer the event is about.
subscriptionobjectyesThe subscription the package is on.
packageWebhookPackageyesThe package when the event is triggered.

WebhookCustomer

The customer the event is about.

FieldTypeRequiredDescription
idstringyesThe customer's Clocknext id.
namestringyesThe customer's name.

PackageEventData.subscription

The subscription the package is on.

FieldTypeRequiredDescription
idstringyesThe subscription's id — its purchaseId in the Subscriptions API.

WebhookPackage

The package on the subscription when the event is triggered, as packages on Get a subscription shows it, in snake_case.

FieldTypeRequiredDescription
idstringyesThe id of the package on the subscription (PurchasePackage.id).
package_idstring | nullyesThe catalog package it was added from. Null when that package is gone.
namestringyesThe package's name when it was added.
status"SCHEDULED" | "ACTIVE" | "MARKED_FOR_CANCELLATION" | "CANCELLED"yesACTIVE, MARKED_FOR_CANCELLATION or CANCELLED.
costnumberyesThe price for each billing cycle when it was added, in USD.
entitlementsobjectyesWhat it grants each cycle, grouped by kind. Every group is always present.
started_atstring | nullyesWhen it started.
ends_atstring | nullyesWhen it ends or ended. Null while it renews.
ended_atstring | nullyesWhen it ended. Null unless CANCELLED.
ended_reason"REMOVED" | "INVOICE_VOIDED" | "PLAN_CHANGED" | "SUBSCRIPTION_CANCELLED" | nullyesWhy it ended. Null unless CANCELLED.
cancel_reasonstring | nullyesThe reason sent with the remove. Null when none.
invoice_idstring | nullyesThe id of the invoice it was added on.

WebhookPackage.entitlements

What it grants each cycle, grouped by kind. Every group is always present.

FieldTypeRequiredDescription
creditsWebhookPackageEntitlementItem[]yesThe credits and their quantities.
outcomesWebhookPackageEntitlementItem[]yesThe outcomes and their quantities.
unitsWebhookPackageEntitlementItem[]yesThe units and their quantities.
compositesWebhookPackageEntitlementItem[]yesThe composites and their quantities.
flat_feenumber | nullyesThe flat fee in USD each cycle. Null when there is none.

WebhookPackageEntitlementItem

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.

subscription.cancelled POST

Triggered when a subscription ends — cancelled, replaced by a plan change, or unpaid.

package.removal_scheduled POST

Triggered when a package is removed with `atPeriodEnd: true`. It keeps working until `ends_at`, the end of its paid period.