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
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
application/json- body
customerId?stringThe customer. Send this or externalId; customerId wins if both.
externalId?stringYour own id for the customer, in place of customerId.
toPlanId*stringThe plan to move to. It must be active and differ from the current plan.
notes?stringA note for your records. At most 500 characters.
length <= 500startNewCycle?booleanSame billing cycle: true starts a new period today at the full price. Default false.
autoPayment?booleantrue: the balance, then the saved card, pay the new invoice; auto-payment on. Default false.
falseWhat the plan change would do.
application/json- response
statusCode*integerThe 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"}'{ "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
| Field | Type | Required | Description |
|---|---|---|---|
customerId | string | no | The customer. Send this or externalId; customerId wins if both. |
externalId | string | no | Your own id for the customer, in place of customerId. |
toPlanId | string | yes | The plan to move to. It must be active and differ from the current plan. |
notes | string | no | A note for your records. At most 500 characters. |
startNewCycle | boolean | no | Same billing cycle: true starts a new period today at the full price. Default false. |
autoPayment | boolean | no | true: 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.
| Field | Type | Required | Description |
|---|---|---|---|
effectiveDate | string | yes | The day it would take effect (today, UTC), YYYY-MM-DD. |
from | object | yes | The plan that would end. |
to | object | yes | The plan it would move to. |
sameCycle | boolean | yes | true: both plans bill on the same cycle. See startsNewCycle for the new period. |
startsNewCycle | boolean | yes | true: a new period starts today. false: the renewal date stays, or the plan is free. |
days | object | yes | Days of the old plan's period. |
credit | object | yes | Money that would go to the invoice balance. Its amounts are null when nothing would. |
charge | object | yes | What the new plan would cost. |
newPeriod | PlanChangePeriod | null | yes | The new plan's first period. null for a free plan. |
entitlementsProrated | boolean | yes | true when the first period's quantities are prorated. |
entitlements | PlanChangeEntitlementLine[] | yes | The new plan's entitlements. |
balance | object | yes | The customer's invoice balance before and after. |
PlanChangePreview.from
The plan that would end.
| Field | Type | Required | Description |
|---|---|---|---|
purchaseId | string | yes | Its purchase. |
planName | string | yes | Its name. |
billingCycle | BillingCycle | yes | Its billing cycle. |
period | PlanChangePeriod | yes | Its 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.
| Field | Type | Required | Description |
|---|---|---|---|
startAt | string | yes | When the period starts. |
endAt | string | yes | When the next period starts. |
PlanChangePreview.to
The plan it would move to.
| Field | Type | Required | Description |
|---|---|---|---|
planId | string | yes | Its id. |
planName | string | yes | Its name. |
billingCycle | BillingCycle | yes | Its billing cycle. |
priceUsd | number | yes | Its full price, in USD. |
PlanChangePreview.to.billingCycle
Its billing cycle.
PlanChangePreview.days
Days of the old plan's period.
| Field | Type | Required | Description |
|---|---|---|---|
inPeriod | integer | yes | Days in the period. |
used | integer | yes | Days used, up to and including today. |
remaining | integer | yes | Days left unused. |
PlanChangePreview.credit
Money that would go to the invoice balance. Its amounts are null when nothing would.
| Field | Type | Required | Description |
|---|---|---|---|
paidUsd | number | null | yes | What the old plan's invoice was paid, in USD. |
subtotalUsd | number | null | yes | The credit before tax, in USD. |
taxUsd | number | null | yes | The tax given back, in USD. |
totalUsd | number | null | yes | The credit in total, in USD. |
invoiceNumber | string | null | yes | The 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" | null | yes | Why nothing would be credited. null when something would. |
PlanChangePreview.charge
What the new plan would cost.
| Field | Type | Required | Description |
|---|---|---|---|
subtotalUsd | number | yes | The price before tax, in USD. |
taxUsd | number | yes | An estimate, with today's tax rates. |
totalUsd | number | yes | The total, in USD. |
billing | "INVOICE_NOW" | "NOTHING_TO_INVOICE" | yes | INVOICE_NOW: invoiced now. NOTHING_TO_INVOICE: nothing is charged, such as a free plan. |
prorated | boolean | yes | true: the price of the rest of the period, not the full price. |
label | string | null | yes | The invoice line's label. |
PlanChangePeriod
A billing period. endAt is exclusive: it is the instant the next period starts.
| Field | Type | Required | Description |
|---|---|---|---|
startAt | string | yes | When the period starts. |
endAt | string | yes | When the next period starts. |
PlanChangeEntitlementLine
One entitlement of the new plan: its full quantity and what the first period gets.
| Field | Type | Required | Description |
|---|---|---|---|
type | "WALLET" | "CREDIT" | "OUTCOME" | "UNIT" | "COMPOSITE" | yes | The entitlement's kind. |
name | string | yes | Its name. |
full | number | yes | The plan's own quantity. USD for the wallet. |
firstPeriod | number | yes | What the customer gets for the first period. |
PlanChangePreview.balance
The customer's invoice balance before and after.
| Field | Type | Required | Description |
|---|---|---|---|
currentUsd | number | yes | The balance now. |
afterCreditUsd | number | yes | The balance after the credit. |
wouldPayUsd | number | yes | What the balance would pay of the new invoice; 0 without autoPayment: true. |
stillOwedUsd | number | yes | What 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.