Cancel a subscription
Cancels a subscription now, or with atPeriodEnd: true at the end of its period (MARKED_FOR_CANCELLATION). Without atPeriodEnd, a marked one ends now. Add proration: REFUND_UNUSED_TIME and a refundTo to give back the unused time as a credit note. A refund that can't be made leaves it running.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringThe purchase id of the subscription.
application/json- body
reason?stringWhy it is cancelled. Optional; at most 200 characters.
1 <= length <= 200atPeriodEnd?booleantrue ends it at the end of the current period. Default: now. Not started or FREE: always now.
falseproration?stringREFUND_UNUSED_TIME cancels now and refunds the unused days, to refundTo. Default NONE.
"NONE""NONE""REFUND_UNUSED_TIME"refundTo?stringWhere a refund goes: INVOICE_BALANCE or CARD. Required with REFUND_UNUSED_TIME.
"INVOICE_BALANCE""CARD"Cancelled or marked. creditNoteId, creditNote and invoice are set only when the unused time was refunded.
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 result of the cancellation.
curl -X POST 'https://payments.clocknext.com/api/v1/subscriptions/pur_ghi789/cancel' \ -H 'Content-Type: application/json' \ -d '{ "reason": "Moving to an in-house tool at renewal", "atPeriodEnd": true}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Subscription marked for cancellation." }, "result": { "mode": "marked", "endsAt": "2026-11-20T00:00:00.000Z", "subscription": { "purchaseId": "cmvgvkq9x004r08l28dpahwhv", "customerId": "cmvgvklx5002f08l2875y93k8", "planId": "cmvgvgfob001m08l2upi4aokj", "subscriptionNumber": "SUB-006", "status": "MARKED_FOR_CANCELLATION", "startsAt": "2026-10-20T16:06:37.953Z", "periodStart": "2026-10-20T00:00:00.000Z", "periodEnd": "2026-11-20T00:00:00.000Z", "nextRenewalDate": null, "holdEndsAt": null, "cancelRequestedAt": "2026-10-20T16:08:55.752Z", "endsAt": "2026-11-20T00:00:00.000Z", "cancelReason": "Moving to an in-house tool at renewal", "packages": [] }, "creditNoteId": null, "creditNote": null, "invoice": null }}Types
Every object type on this page, with its fields.
CancelSubscriptionInput
| Field | Type | Required | Description |
|---|---|---|---|
reason | string | no | Why it is cancelled. Optional; at most 200 characters. |
atPeriodEnd | boolean | no | true ends it at the end of the current period. Default: now. Not started or FREE: always now. |
proration | "NONE" | "REFUND_UNUSED_TIME" | no | REFUND_UNUSED_TIME cancels now and refunds the unused days, to refundTo. Default NONE. |
refundTo | "INVOICE_BALANCE" | "CARD" | no | Where a refund goes: INVOICE_BALANCE or CARD. Required with REFUND_UNUSED_TIME. |
Subscription
One period of a subscription.
| Field | Type | Required | Description |
|---|---|---|---|
purchaseId | string | yes | The purchase this period belongs to; all periods share it. Use it to get or cancel the subscription. |
customerId | string | yes | The id of the customer who holds the subscription. |
planId | string | null | yes | The id of the plan bought. null when that plan was deleted later. |
subscriptionNumber | string | null | yes | This period's reference, such as SUB-0004; each renewal gets a new one. null on older purchases. |
status | "SCHEDULED" | "ACTIVE" | "MARKED_FOR_CANCELLATION" | "RENEWED" | "CANCELLED" | yes | SCHEDULED, ACTIVE, MARKED_FOR_CANCELLATION, RENEWED or CANCELLED. |
startsAt | string | null | yes | When this period started; the planned date while SCHEDULED. |
periodStart | string | null | yes | The start of the period this row covers; null when it is not running. |
periodEnd | string | null | yes | The end of the period this row covers. null when it is not running. |
nextRenewalDate | string | null | yes | The end of the running period; null when it will not renew. |
holdEndsAt | string | null | yes | The deadline to pay: a held renewal's, or a SCHEDULED period's first invoice's. Null otherwise. |
cancelRequestedAt | string | null | yes | When it was marked to cancel at period end. null otherwise, and always on a RENEWED row. |
endsAt | string | null | yes | When a running subscription ends (marked for cancellation, or a plan change). Else null. |
cancelReason | string | null | yes | The reason given when it was cancelled; null when none. |
packages | PurchasePackage[] | yes | Its packages that are scheduled, active or marked for cancellation, oldest first. Empty on RENEWED. |
PurchasePackage
A package on a subscription. name, cost and entitlements are the copy taken when it was added: a later catalog edit doesn't change them.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The id of the package on this subscription. Use it to remove the package. |
packageId | string | null | yes | The catalog package it was added from. null when that package is gone. |
name | string | yes | The package's name when it was added. |
status | "SCHEDULED" | "ACTIVE" | "MARKED_FOR_CANCELLATION" | "CANCELLED" | yes | SCHEDULED (invoice unpaid), ACTIVE, MARKED_FOR_CANCELLATION (ends at endsAt) or CANCELLED. |
cost | number | yes | The price for each billing cycle when it was added, in USD. |
entitlements | PackageEntitlements | yes | What it grants each cycle, grouped by kind. |
startedAt | string | null | yes | When it started (its invoice was paid). null while SCHEDULED. |
endsAt | string | null | yes | When it ends or ended, the end of its paid period when marked. Else null. |
endedAt | string | null | yes | When it ended. null unless CANCELLED. |
endedReason | "REMOVED" | "INVOICE_VOIDED" | "PLAN_CHANGED" | "SUBSCRIPTION_CANCELLED" | null | yes | Why it ended. null unless CANCELLED. |
cancelReason | string | null | yes | The reason sent with the remove. null when none. |
notes | string | null | yes | The notes sent with the add, such as a reference or PO number. null when none. |
invoiceId | string | null | yes | The id of the invoice it was added on. |
PackageEntitlements
What a package grants each cycle, grouped by kind. Every group is always present: an empty list, and flatFee null when there is none.
| Field | Type | Required | Description |
|---|---|---|---|
credits | PackageEntitlementItem[] | yes | The credits and their quantities. |
outcomes | PackageEntitlementItem[] | yes | The outcomes and their quantities. |
units | PackageEntitlementItem[] | yes | The units and their quantities. |
composites | PackageEntitlementItem[] | yes | The composites and their quantities. |
flatFee | number | null | yes | The flat fee in USD, charged each cycle. null when there is none. |
PackageEntitlementItem
One credit, outcome, unit or composite of a package, with the quantity it grants each cycle.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The credit's, outcome's, unit's or composite's own id. |
name | string | yes | Its name. |
quantity | integer | yes | How many it grants each cycle. |
CreditNote
A document that lowers an invoice, in full or in part.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The credit note's id. |
creditNoteNumber | string | yes | Its reference, such as CN-001. One sequence per workspace. |
invoiceId | string | yes | The invoice it lowers. |
invoiceNumber | string | yes | That invoice's reference. |
customerId | string | yes | The customer of the invoice. |
customerName | string | yes | The customer's name. |
destination | CreditNoteDestination | yes | What it did with its amount. |
status | "ISSUED" | "VOID" | yes | ISSUED, or VOID when it was cancelled while its invoice was open. |
reasonCode | CreditNoteReasonCode | yes | Why it was made. |
reasonLabel | string | yes | The reason in words, such as Order changed. |
memo | string | null | yes | Your note on it. null when none. |
subtotalUsd | number | yes | The amount before tax, in USD. |
taxUsd | number | yes | The tax given back, in USD. |
totalUsd | number | yes | The total in USD: subtotalUsd plus taxUsd. |
currencyCode | string | yes | USD for every invoice issued since Clocknext stopped converting money (every invoice and charge is USD). An older invoice keeps the customer's currency it was issued with. |
taxes | CreditNoteTax[] | yes | The tax given back, per tax rate. |
createdAt | string | yes | When it was made. |
createdBy | object | null | yes | Who made it. null for a note the system made. |
voidedAt | string | null | yes | When it was voided. null while issued. |
refund | object | null | yes | The card refund this note asked for. null when there is none. |
CreditNote.destination
What a credit note does with its amount. An OPEN invoice takes REDUCE_OPEN_INVOICE; a PAID one takes the other two.
CreditNote.reasonCode
Why a credit note was made. PLAN_CHANGE_UNUSED_TIME is the note a plan change makes itself; SUBSCRIPTION_CANCELLED_UNUSED_TIME is the note a cancel makes when it refunds the unused time. New values can be added: handle one you don't know.
CreditNoteTax
The part of a credit note's tax that one tax rate gave back.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The tax's name, saved on the invoice. |
percentage | number | yes | The tax rate in percent. |
behavior | "INCLUSIVE" | "EXCLUSIVE" | yes | INCLUSIVE: already inside the price. EXCLUSIVE: added on top. |
taxableAmountUsd | number | yes | USD this credit's tax was worked out on. |
amountUsd | number | yes | The tax given back, in USD. |
CreditNote.createdBy
The person or key owner who made it.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | Their id. |
name | string | yes | Their name. |
CreditNote.refund
The card refund behind the note.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The refund's id. |
status | "PENDING_AT_GATEWAY" | "SUCCEEDED" | "FAILED" | "REJECTED_IN_GATEWAY_REVIEW" | yes | PENDING_AT_GATEWAY until the gateway finishes. A failed or rejected refund returns the money. |
failureReason | string | null | yes | Why it failed, if it did. null otherwise. |
InvoiceCreditSummary
An invoice as a write that changed it shows it: what is owed after the credit note or the void.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The invoice's id. |
invoiceNumber | string | yes | Its reference. |
status | InvoiceStatus | yes | Its status. PAID when a credit note settled it. |
amount | number | yes | The invoice total in USD, tax included. |
creditedUsd | number | yes | All credit notes on it, in USD, tax included. |
balanceAppliedUsd | number | yes | What the customer's invoice balance paid, in USD. |
amountDueUsd | number | yes | What is still owed, in USD. 0 unless it is OPEN. |
InvoiceCreditSummary.status
OPEN: not paid yet. PAID: paid. VOID: voided. AUTO_CLOSED: a recurring invoice closed by "Auto close invoices on recurring"; applied as paid, with no payment collected.
Get a subscription GET
One subscription, by its purchase id: the period running now, with every period it renewed out of in `periods`, newest first. An unknown id is a `404` "Subscription not found."
Add packages to a subscription POST
Adds 1 to 10 packages to a running subscription, on one invoice with a line for each at its full price. They are `SCHEDULED` until it is paid, then `ACTIVE`, or `ACTIVE` at once with `recordAsPaid`. When the organization uses the invoice balance for new invoices, the customer's invoice balance pays the invoice first. Paid in full, it comes back `PAID` with no `payUrl` and the packages are `ACTIVE` at once. They renew with the subscription until removed. See [Packages](/docs/documentation/packages).