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

List subscriptions

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.

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

GET
/subscriptions

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Query Parameters

customerId?string

Restrict results to this customer.

status?string

Only rows with this status (any letter case).

Value in"SCHEDULED""ACTIVE""MARKED_FOR_CANCELLATION""RENEWED""CANCELLED"
limit?integer

How many PURCHASES on one page: default 50, maximum 50 (a bigger value is cut to 50). It counts purchases, not periods, so the rows of one purchase are never split across two pages. Zero, a negative number or a non-number is a 400.

Range1 <= value <= 50
Default50
cursor?string

The nextCursor of the previous page (a purchase id). Omit it for the first page.

Response Body

Subscriptions.

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*

One page of subscription periods.

Example Request
curl -X GET 'https://payments.clocknext.com/api/v1/subscriptions?customerId=cus_abc123&status=ACTIVE&limit=50'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "subscriptions": [      {        "purchaseId": "cmvgvksil005p08l2ggbacq1l",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "planId": "cmvgvgfob001m08l2upi4aokj",        "subscriptionNumber": "SUB-008",        "status": "CANCELLED",        "startsAt": "2026-10-20T00:00:00.000Z",        "periodStart": null,        "periodEnd": null,        "nextRenewalDate": null,        "holdEndsAt": null,        "cancelRequestedAt": null,        "endsAt": null,        "cancelReason": "Created by mistake — customer stays on Pro",        "packages": []      },      {        "purchaseId": "cmvgvkq9x004r08l28dpahwhv",        "customerId": "cmvgvklx5002f08l2875y93k8",        "planId": "cmvgvgfob001m08l2upi4aokj",        "subscriptionNumber": "SUB-006",        "status": "MARKED_FOR_CANCELLATION",        "startsAt": "2026-10-20T16:06:37.953Z",        "periodStart": "2026-10-20T00:00:00.000Z",        "periodEnd": "2026-11-20T00:00:00.000Z",        "nextRenewalDate": null,        "holdEndsAt": null,        "cancelRequestedAt": "2026-10-20T16:08:55.752Z",        "endsAt": "2026-11-20T00:00:00.000Z",        "cancelReason": "Moving to an in-house tool at renewal",        "packages": []      },      {        "purchaseId": "cmvgvkptw004i08l2d8vveucu",        "customerId": "cmvgv9650000407iigjb3lt2p",        "planId": "cmvgvg38w001808l2j7k6ykx3",        "subscriptionNumber": "SUB-005",        "status": "SCHEDULED",        "startsAt": "2026-11-03T00:00:00.000Z",        "periodStart": null,        "periodEnd": null,        "nextRenewalDate": null,        "holdEndsAt": "2026-11-10T00:00:00.000Z",        "cancelRequestedAt": null,        "endsAt": null,        "cancelReason": null,        "packages": []      },      {        "purchaseId": "cmvgvkp6r004a08l22itk1bh6",        "customerId": "cmvgv9elh000807iixkqqodos",        "planId": "cmvgvg2dn000n08l23x83smgo",        "subscriptionNumber": null,        "status": "ACTIVE",        "startsAt": "2026-10-20T00:00:00.000Z",        "periodStart": null,        "periodEnd": null,        "nextRenewalDate": null,        "holdEndsAt": null,        "cancelRequestedAt": null,        "endsAt": null,        "cancelReason": null,        "packages": []      }    ],    "nextCursor": null  }}

Types

Every object type on this page, with its fields.

Subscription

One period of a subscription.

FieldTypeRequiredDescription
purchaseIdstringyesThe purchase this period belongs to; all periods share it. Use it to get or cancel the subscription.
customerIdstringyesThe id of the customer who holds the subscription.
planIdstring | nullyesThe id of the plan bought. null when that plan was deleted later.
subscriptionNumberstring | nullyesThis period's reference, such as SUB-0004; each renewal gets a new one. null on older purchases.
status"SCHEDULED" | "ACTIVE" | "MARKED_FOR_CANCELLATION" | "RENEWED" | "CANCELLED"yesSCHEDULED, ACTIVE, MARKED_FOR_CANCELLATION, RENEWED or CANCELLED.
startsAtstring | nullyesWhen this period started; the planned date while SCHEDULED.
periodStartstring | nullyesThe start of the period this row covers; null when it is not running.
periodEndstring | nullyesThe end of the period this row covers. null when it is not running.
nextRenewalDatestring | nullyesThe end of the running period; null when it will not renew.
holdEndsAtstring | nullyesThe deadline to pay: a held renewal's, or a SCHEDULED period's first invoice's. Null otherwise.
cancelRequestedAtstring | nullyesWhen it was marked to cancel at period end. null otherwise, and always on a RENEWED row.
endsAtstring | nullyesWhen a running subscription ends (marked for cancellation, or a plan change). Else null.
cancelReasonstring | nullyesThe reason given when it was cancelled; null when none.
packagesPurchasePackage[]yesIts packages that are scheduled, active or marked for cancellation, oldest first. Empty on RENEWED.

PurchasePackage

A package on a subscription. name, cost and entitlements are the copy taken when it was added: a later catalog edit doesn't change them.

FieldTypeRequiredDescription
idstringyesThe id of the package on this subscription. Use it to remove the package.
packageIdstring | 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"yesSCHEDULED (invoice unpaid), ACTIVE, MARKED_FOR_CANCELLATION (ends at endsAt) or CANCELLED.
costnumberyesThe price for each billing cycle when it was added, in USD.
entitlementsPackageEntitlementsyesWhat it grants each cycle, grouped by kind.
startedAtstring | nullyesWhen it started (its invoice was paid). null while SCHEDULED.
endsAtstring | nullyesWhen it ends or ended, the end of its paid period when marked. Else null.
endedAtstring | nullyesWhen it ended. null unless CANCELLED.
endedReason"REMOVED" | "INVOICE_VOIDED" | "PLAN_CHANGED" | "SUBSCRIPTION_CANCELLED" | nullyesWhy it ended. null unless CANCELLED.
cancelReasonstring | nullyesThe reason sent with the remove. null when none.
notesstring | nullyesThe notes sent with the add, such as a reference or PO number. null when none.
invoiceIdstring | nullyesThe id of the invoice it was added on.

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.

Create a checkout POST

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`).

Get a subscription GET

One subscription, by its purchase id: the period running now, with every period it renewed out of in `periods`, newest first. An unknown id is a `404` "Subscription not found."