Change a customer's plan
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.
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.
falseidempotencyKey?string1–200 characters. A repeat with the same key and body replays the first change.
1 <= length <= 200The same key made this change before; nothing new was made.
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' \ -H 'Content-Type: application/json' \ -d '{ "customerId": "cmvgva5po000c07iir1vtn8vl", "toPlanId": "cmvgvgfob001m08l2upi4aokj", "notes": "Downgrade requested by the customer", "idempotencyKey": "pc-northwind-starter"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Plan change already made." }, "result": { "planChange": { "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" }, "replayed": true }}Types
Every object type on this page, with its fields.
CreatePlanChangeInput
| 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. |
idempotencyKey | string | no | 1–200 characters. A repeat with the same key and body replays the first change. |
PlanChange
A move of a customer to another plan, with the unused time of the old plan credited.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The plan change's id. |
customerId | string | yes | The customer. |
status | "IN_PROGRESS" | "DONE" | "FAILED" | yes | IN_PROGRESS while it runs (a retry finishes it), DONE when finished, FAILED with a failureReason. |
failureReason | string | null | yes | Why it failed. null unless FAILED. |
effectiveDate | string | yes | The day it took effect and the old plan ended, YYYY-MM-DD (UTC). |
from | object | yes | The plan that ended. |
to | object | yes | The plan the customer moved to. |
days | object | yes | Days of the old plan's period. |
credit | object | yes | What went to the invoice balance for the unused time. The amounts are null when nothing did. |
charge | object | yes | What the new plan costs for the rest of the period. |
createdAt | string | yes | When it was requested. |
executedAt | string | null | yes | When it finished. null until then. |
PlanChange.from
The plan that ended.
| Field | Type | Required | Description |
|---|---|---|---|
purchaseId | string | yes | Its purchase. |
planName | string | yes | Its name. |
PlanChange.to
The plan the customer moved to.
| Field | Type | Required | Description |
|---|---|---|---|
planId | string | null | yes | Its id. null if the plan was deleted. |
planName | string | yes | Its name. |
purchaseId | string | null | yes | Its purchase. null until it is made. |
PlanChange.days
Days of the old plan's period.
| Field | Type | Required | Description |
|---|---|---|---|
inPeriod | integer | null | yes | Days in the period. |
remaining | integer | null | yes | Days left unused. |
PlanChange.credit
What went to the invoice balance for the unused time. The amounts are null when nothing did.
| Field | Type | Required | Description |
|---|---|---|---|
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. |
creditNoteId | string | null | yes | The credit note that made it. |
PlanChange.charge
What the new plan costs for the rest of the period.
| Field | Type | Required | Description |
|---|---|---|---|
subtotalUsd | number | null | yes | The price before tax, in USD. null until worked out. |
invoiceId | string | null | yes | The new plan's first invoice. null when none. |
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.
Get a plan change GET
One plan change: its status, the days, the credit and charge it worked out, the credit note and invoice it made, and the new purchase.