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 plan changes

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

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

GET
/plan-changes

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Query Parameters

customerId?string

Restrict results to this customer.

status?string

Filter by status (case-insensitive).

Value in"IN_PROGRESS""DONE""FAILED"
limit?integer

Rows on one page: default 50, maximum 50 (a bigger value is cut to 50). Zero, a negative number or a non-number is a 400.

Range1 <= value <= 50
Default50
cursor?string

Id to page after — the last id of the previous page.

Response Body

Plan changes.

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 plan changes.

Example Request
curl -X GET 'https://payments.clocknext.com/api/v1/plan-changes?customerId=cus_abc123&status=DONE&limit=50&cursor=cus_zzz789'
Example Response
{  "statusCode": 200,  "statusDetail": {    "status": "SUCCESS",    "message": "Request processed successfully."  },  "result": {    "planChanges": [      {        "id": "cmvgwf8ab000e08l5p1r6s4zc",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "status": "DONE",        "failureReason": null,        "effectiveDate": "2026-10-28",        "from": {          "purchaseId": "cmvgvkmxz002h08l2h2i1dnsr",          "planName": "Pro"        },        "to": {          "planId": "cmvgvgfob001m08l2upi4aokj",          "planName": "Starter",          "purchaseId": "cmvgwg2jx000d08l5c9m2w5ts"        },        "days": {          "inPeriod": 31,          "remaining": 22        },        "credit": {          "subtotalUsd": 379.81,          "taxUsd": 0,          "totalUsd": 379.81,          "creditNoteId": "cmvgwcm7e000e08l5a3x1v9ty"        },        "charge": {          "subtotalUsd": 22.07,          "invoiceId": "cmvgwg2kp000f08l5d7n3q8vx"        },        "createdAt": "2026-10-28T09:14:07.000Z",        "executedAt": "2026-10-28T09:14:09.000Z"      },      {        "id": "cmvgwf2xe000d08l5t9w3n6hv",        "customerId": "cmvgva5po000c07iir1vtn8vl",        "status": "FAILED",        "failureReason": "The new plan could not be set up.",        "effectiveDate": "2026-10-28",        "from": {          "purchaseId": "cmvgvkmxz002h08l2h2i1dnsr",          "planName": "Pro"        },        "to": {          "planId": "cmvgvgfob001m08l2upi4aokj",          "planName": "Starter",          "purchaseId": null        },        "days": {          "inPeriod": 31,          "remaining": 22        },        "credit": {          "subtotalUsd": null,          "taxUsd": null,          "totalUsd": null,          "creditNoteId": null        },        "charge": {          "subtotalUsd": null,          "invoiceId": null        },        "createdAt": "2026-10-21T10:01:00.000Z",        "executedAt": null      }    ],    "nextCursor": null  }}

Types

Every object type on this page, with its fields.

PlanChange

A move of a customer to another plan, with the unused time of the old plan credited.

FieldTypeRequiredDescription
idstringyesThe plan change's id.
customerIdstringyesThe customer.
status"IN_PROGRESS" | "DONE" | "FAILED"yesIN_PROGRESS while it runs (a retry finishes it), DONE when finished, FAILED with a failureReason.
failureReasonstring | nullyesWhy it failed. null unless FAILED.
effectiveDatestringyesThe day it took effect and the old plan ended, YYYY-MM-DD (UTC).
fromobjectyesThe plan that ended.
toobjectyesThe plan the customer moved to.
daysobjectyesDays of the old plan's period.
creditobjectyesWhat went to the invoice balance for the unused time. The amounts are null when nothing did.
chargeobjectyesWhat the new plan costs for the rest of the period.
createdAtstringyesWhen it was requested.
executedAtstring | nullyesWhen it finished. null until then.

PlanChange.from

The plan that ended.

FieldTypeRequiredDescription
purchaseIdstringyesIts purchase.
planNamestringyesIts name.

PlanChange.to

The plan the customer moved to.

FieldTypeRequiredDescription
planIdstring | nullyesIts id. null if the plan was deleted.
planNamestringyesIts name.
purchaseIdstring | nullyesIts purchase. null until it is made.

PlanChange.days

Days of the old plan's period.

FieldTypeRequiredDescription
inPeriodinteger | nullyesDays in the period.
remaininginteger | nullyesDays left unused.

PlanChange.credit

What went to the invoice balance for the unused time. The amounts are null when nothing did.

FieldTypeRequiredDescription
subtotalUsdnumber | nullyesThe credit before tax, in USD.
taxUsdnumber | nullyesThe tax given back, in USD.
totalUsdnumber | nullyesThe credit in total, in USD.
creditNoteIdstring | nullyesThe credit note that made it.

PlanChange.charge

What the new plan costs for the rest of the period.

FieldTypeRequiredDescription
subtotalUsdnumber | nullyesThe price before tax, in USD. null until worked out.
invoiceIdstring | nullyesThe new plan's first invoice. null when none.

Remove a package from a subscription POST

Removes a package now (`CANCELLED`), or with `atPeriodEnd: true` at the end of its paid period (`MARKED_FOR_CANCELLATION`). Removed now, what is left of it is taken back; nothing is refunded. On hold, it ends now and its line comes off the unpaid renewal, returned in `invoice`.

Preview a plan change POST

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.