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
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
customerId?stringRestrict results to this customer.
status?stringFilter by status (case-insensitive).
"IN_PROGRESS""DONE""FAILED"limit?integerRows 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.
1 <= value <= 5050cursor?stringId to page after — the last id of the previous page.
Plan changes.
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*One page of plan changes.
curl -X GET 'https://payments.clocknext.com/api/v1/plan-changes?customerId=cus_abc123&status=DONE&limit=50&cursor=cus_zzz789'{ "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.
| 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. |
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.