Get a plan change
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.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringPlan change id.
The plan change.
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 GET 'https://payments.clocknext.com/api/v1/plan-changes/cmvgwf8ab000e08l5p1r6s4zc'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "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" } }}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.
| 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. |
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.
List invoices GET
Newest first, paged with `limit` (at most 50) and `cursor` → `nextCursor` — see [Paginating results](/docs/api-reference/pagination). Any other query parameter is a `400` ("Unknown parameter `offset`.").