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

Preview a plan change

Shows what a plan change would do, without doing it: the days of the old plan, the credit for the unused time, the charge with an estimated tax, the new period, and what the balance would pay. Takes the same body as creating one. Changes nothing.

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

POST
/plan-changes/preview

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Request Body

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

The customer. Send this or externalId; customerId wins if both.

externalId?string

Your own id for the customer, in place of customerId.

toPlanId*string

The plan to move to. It must be active and differ from the current plan.

notes?string

A note for your records. At most 500 characters.

Lengthlength <= 500
startNewCycle?boolean

Same billing cycle: true starts a new period today at the full price. Default false.

autoPayment?boolean

true: the balance, then the saved card, pay the new invoice; auto-payment on. Default false.

Defaultfalse

Response Body

What the plan change would do.

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 data of the answer.

curl -X POST 'https://payments.clocknext.com/api/v1/plan-changes/preview' \  -H 'Content-Type: application/json' \  -d '{  "customerId": "cmvgva5po000c07iir1vtn8vl",  "toPlanId": "cmvgvgfob001m08l2upi4aokj"}'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "preview": {      "effectiveDate": "2026-10-28",      "from": {        "purchaseId": "cmvgvkmxz002h08l2h2i1dnsr",        "planName": "Pro",        "billingCycle": "MONTHLY",        "period": {          "startAt": "2026-10-20T07:41:12.000Z",          "endAt": "2026-11-20T07:41:12.000Z"        }      },      "to": {        "planId": "cmvgvgfob001m08l2upi4aokj",        "planName": "Starter",        "billingCycle": "MONTHLY",        "priceUsd": 31.1      },      "sameCycle": true,      "startsNewCycle": false,      "days": {        "inPeriod": 31,        "used": 9,        "remaining": 22      },      "credit": {        "paidUsd": 535.18,        "subtotalUsd": 379.81,        "taxUsd": 0,        "totalUsd": 379.81,        "invoiceNumber": "INV-0001",        "noCreditReason": null      },      "charge": {        "subtotalUsd": 22.07,        "taxUsd": 0,        "totalUsd": 22.07,        "billing": "INVOICE_NOW",        "prorated": true,        "label": "Starter, 28 Oct – 19 Nov"      },      "newPeriod": {        "startAt": "2026-10-28T09:14:07.000Z",        "endAt": "2026-11-20T07:41:12.000Z"      },      "entitlementsProrated": true,      "entitlements": [        {          "type": "CREDIT",          "name": "Deep Research",          "full": 100,          "firstPeriod": 71        }      ],      "balance": {        "currentUsd": 0,        "afterCreditUsd": 379.81,        "wouldPayUsd": 22.07,        "stillOwedUsd": 0      }    }  }}

Types

Every object type on this page, with its fields.

PlanChangeInput

FieldTypeRequiredDescription
customerIdstringnoThe customer. Send this or externalId; customerId wins if both.
externalIdstringnoYour own id for the customer, in place of customerId.
toPlanIdstringyesThe plan to move to. It must be active and differ from the current plan.
notesstringnoA note for your records. At most 500 characters.
startNewCyclebooleannoSame billing cycle: true starts a new period today at the full price. Default false.
autoPaymentbooleannotrue: the balance, then the saved card, pay the new invoice; auto-payment on. Default false.

PlanChangePreview

What a plan change would do, worked out without doing it.

FieldTypeRequiredDescription
effectiveDatestringyesThe day it would take effect (today, UTC), YYYY-MM-DD.
fromobjectyesThe plan that would end.
toobjectyesThe plan it would move to.
sameCyclebooleanyestrue: both plans bill on the same cycle. See startsNewCycle for the new period.
startsNewCyclebooleanyestrue: a new period starts today. false: the renewal date stays, or the plan is free.
daysobjectyesDays of the old plan's period.
creditobjectyesMoney that would go to the invoice balance. Its amounts are null when nothing would.
chargeobjectyesWhat the new plan would cost.
newPeriodPlanChangePeriod | nullyesThe new plan's first period. null for a free plan.
entitlementsProratedbooleanyestrue when the first period's quantities are prorated.
entitlementsPlanChangeEntitlementLine[]yesThe new plan's entitlements.
balanceobjectyesThe customer's invoice balance before and after.

PlanChangePreview.from

The plan that would end.

FieldTypeRequiredDescription
purchaseIdstringyesIts purchase.
planNamestringyesIts name.
billingCycleBillingCycleyesIts billing cycle.
periodPlanChangePeriodyesIts current billing period.

PlanChangePreview.from.billingCycle

Its billing cycle.

PlanChangePreview.from.period

A billing period. endAt is exclusive: it is the instant the next period starts.

FieldTypeRequiredDescription
startAtstringyesWhen the period starts.
endAtstringyesWhen the next period starts.

PlanChangePreview.to

The plan it would move to.

FieldTypeRequiredDescription
planIdstringyesIts id.
planNamestringyesIts name.
billingCycleBillingCycleyesIts billing cycle.
priceUsdnumberyesIts full price, in USD.

PlanChangePreview.to.billingCycle

Its billing cycle.

PlanChangePreview.days

Days of the old plan's period.

FieldTypeRequiredDescription
inPeriodintegeryesDays in the period.
usedintegeryesDays used, up to and including today.
remainingintegeryesDays left unused.

PlanChangePreview.credit

Money that would go to the invoice balance. Its amounts are null when nothing would.

FieldTypeRequiredDescription
paidUsdnumber | nullyesWhat the old plan's invoice was paid, in USD.
subtotalUsdnumber | nullyesThe credit before tax, in USD.
taxUsdnumber | nullyesThe tax given back, in USD.
totalUsdnumber | nullyesThe credit in total, in USD.
invoiceNumberstring | nullyesThe invoice it is credited on.
noCreditReason"CURRENT_PERIOD_HAS_NO_INVOICE" | "CURRENT_INVOICE_NOT_PAID" | "CURRENT_INVOICE_CLOSED_WITHOUT_PAYMENT" | "NO_PREPAID_AMOUNT_LEFT_TO_CREDIT" | nullyesWhy nothing would be credited. null when something would.

PlanChangePreview.charge

What the new plan would cost.

FieldTypeRequiredDescription
subtotalUsdnumberyesThe price before tax, in USD.
taxUsdnumberyesAn estimate, with today's tax rates.
totalUsdnumberyesThe total, in USD.
billing"INVOICE_NOW" | "NOTHING_TO_INVOICE"yesINVOICE_NOW: invoiced now. NOTHING_TO_INVOICE: nothing is charged, such as a free plan.
proratedbooleanyestrue: the price of the rest of the period, not the full price.
labelstring | nullyesThe invoice line's label.

PlanChangePeriod

A billing period. endAt is exclusive: it is the instant the next period starts.

FieldTypeRequiredDescription
startAtstringyesWhen the period starts.
endAtstringyesWhen the next period starts.

PlanChangeEntitlementLine

One entitlement of the new plan: its full quantity and what the first period gets.

FieldTypeRequiredDescription
type"WALLET" | "CREDIT" | "OUTCOME" | "UNIT" | "COMPOSITE"yesThe entitlement's kind.
namestringyesIts name.
fullnumberyesThe plan's own quantity. USD for the wallet.
firstPeriodnumberyesWhat the customer gets for the first period.

PlanChangePreview.balance

The customer's invoice balance before and after.

FieldTypeRequiredDescription
currentUsdnumberyesThe balance now.
afterCreditUsdnumberyesThe balance after the credit.
wouldPayUsdnumberyesWhat the balance would pay of the new invoice; 0 without autoPayment: true.
stillOwedUsdnumberyesWhat the customer would still owe after the balance.

List plan changes GET

Newest first, paged with `limit` (at most 50) and `cursor` → `nextCursor` — see [Paginating results](/docs/api-reference/pagination). Filter by `customerId` and/or `status`. Any other query parameter is a `400`.

Change a customer's plan POST

Moves a customer to another plan. The old plan ends today and its unused time is credited to the invoice balance. The new plan is invoiced and starts when that invoice is paid. Preview it first. With `autoPayment: true` the balance and saved card pay it.