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

Cancel a subscription

Cancels a subscription now, or with atPeriodEnd: true at the end of its period (MARKED_FOR_CANCELLATION). Without atPeriodEnd, a marked one ends now. Add proration: REFUND_UNUSED_TIME and a refundTo to give back the unused time as a credit note. A refund that can't be made leaves it running.

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

POST
/subscriptions/{id}/cancel

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

The purchase id of the subscription.

Request Body

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

Why it is cancelled. Optional; at most 200 characters.

Length1 <= length <= 200
atPeriodEnd?boolean

true ends it at the end of the current period. Default: now. Not started or FREE: always now.

Defaultfalse
proration?string

REFUND_UNUSED_TIME cancels now and refunds the unused days, to refundTo. Default NONE.

Default"NONE"
Value in"NONE""REFUND_UNUSED_TIME"
refundTo?string

Where a refund goes: INVOICE_BALANCE or CARD. Required with REFUND_UNUSED_TIME.

Value in"INVOICE_BALANCE""CARD"

Response Body

Cancelled or marked. creditNoteId, creditNote and invoice are set only when the unused time was refunded.

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 result of the cancellation.

curl -X POST 'https://payments.clocknext.com/api/v1/subscriptions/pur_ghi789/cancel' \  -H 'Content-Type: application/json' \  -d '{  "reason": "Moving to an in-house tool at renewal",  "atPeriodEnd": true}'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Subscription marked for cancellation."  },  "result": {    "mode": "marked",    "endsAt": "2026-11-20T00:00:00.000Z",    "subscription": {      "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": []    },    "creditNoteId": null,    "creditNote": null,    "invoice": null  }}

Types

Every object type on this page, with its fields.

CancelSubscriptionInput

FieldTypeRequiredDescription
reasonstringnoWhy it is cancelled. Optional; at most 200 characters.
atPeriodEndbooleannotrue ends it at the end of the current period. Default: now. Not started or FREE: always now.
proration"NONE" | "REFUND_UNUSED_TIME"noREFUND_UNUSED_TIME cancels now and refunds the unused days, to refundTo. Default NONE.
refundTo"INVOICE_BALANCE" | "CARD"noWhere a refund goes: INVOICE_BALANCE or CARD. Required with REFUND_UNUSED_TIME.

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.

CreditNote

A document that lowers an invoice, in full or in part.

FieldTypeRequiredDescription
idstringyesThe credit note's id.
creditNoteNumberstringyesIts reference, such as CN-001. One sequence per workspace.
invoiceIdstringyesThe invoice it lowers.
invoiceNumberstringyesThat invoice's reference.
customerIdstringyesThe customer of the invoice.
customerNamestringyesThe customer's name.
destinationCreditNoteDestinationyesWhat it did with its amount.
status"ISSUED" | "VOID"yesISSUED, or VOID when it was cancelled while its invoice was open.
reasonCodeCreditNoteReasonCodeyesWhy it was made.
reasonLabelstringyesThe reason in words, such as Order changed.
memostring | nullyesYour note on it. null when none.
subtotalUsdnumberyesThe amount before tax, in USD.
taxUsdnumberyesThe tax given back, in USD.
totalUsdnumberyesThe total in USD: subtotalUsd plus taxUsd.
currencyCodestringyesUSD for every invoice issued since Clocknext stopped converting money (every invoice and charge is USD). An older invoice keeps the customer's currency it was issued with.
taxesCreditNoteTax[]yesThe tax given back, per tax rate.
createdAtstringyesWhen it was made.
createdByobject | nullyesWho made it. null for a note the system made.
voidedAtstring | nullyesWhen it was voided. null while issued.
refundobject | nullyesThe card refund this note asked for. null when there is none.

CreditNote.destination

What a credit note does with its amount. An OPEN invoice takes REDUCE_OPEN_INVOICE; a PAID one takes the other two.

CreditNote.reasonCode

Why a credit note was made. PLAN_CHANGE_UNUSED_TIME is the note a plan change makes itself; SUBSCRIPTION_CANCELLED_UNUSED_TIME is the note a cancel makes when it refunds the unused time. New values can be added: handle one you don't know.

CreditNoteTax

The part of a credit note's tax that one tax rate gave back.

FieldTypeRequiredDescription
namestringyesThe tax's name, saved on the invoice.
percentagenumberyesThe tax rate in percent.
behavior"INCLUSIVE" | "EXCLUSIVE"yesINCLUSIVE: already inside the price. EXCLUSIVE: added on top.
taxableAmountUsdnumberyesUSD this credit's tax was worked out on.
amountUsdnumberyesThe tax given back, in USD.

CreditNote.createdBy

The person or key owner who made it.

FieldTypeRequiredDescription
idstringyesTheir id.
namestringyesTheir name.

CreditNote.refund

The card refund behind the note.

FieldTypeRequiredDescription
idstringyesThe refund's id.
status"PENDING_AT_GATEWAY" | "SUCCEEDED" | "FAILED" | "REJECTED_IN_GATEWAY_REVIEW"yesPENDING_AT_GATEWAY until the gateway finishes. A failed or rejected refund returns the money.
failureReasonstring | nullyesWhy it failed, if it did. null otherwise.

InvoiceCreditSummary

An invoice as a write that changed it shows it: what is owed after the credit note or the void.

FieldTypeRequiredDescription
idstringyesThe invoice's id.
invoiceNumberstringyesIts reference.
statusInvoiceStatusyesIts status. PAID when a credit note settled it.
amountnumberyesThe invoice total in USD, tax included.
creditedUsdnumberyesAll credit notes on it, in USD, tax included.
balanceAppliedUsdnumberyesWhat the customer's invoice balance paid, in USD.
amountDueUsdnumberyesWhat is still owed, in USD. 0 unless it is OPEN.

InvoiceCreditSummary.status

OPEN: not paid yet. PAID: paid. VOID: voided. AUTO_CLOSED: a recurring invoice closed by "Auto close invoices on recurring"; applied as paid, with no payment collected.

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."

Add packages to a subscription POST

Adds 1 to 10 packages to a running subscription, on one invoice with a line for each at its full price. They are `SCHEDULED` until it is paid, then `ACTIVE`, or `ACTIVE` at once with `recordAsPaid`. When the organization uses the invoice balance for new invoices, the customer's invoice balance pays the invoice first. Paid in full, it comes back `PAID` with no `payUrl` and the packages are `ACTIVE` at once. They renew with the subscription until removed. See [Packages](/docs/documentation/packages).