Remove a package from a subscription
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.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringThe purchase id of the subscription.
purchasePackageId*stringThe id of the package on the subscription (PurchasePackage.id), not the catalog package id.
application/json- body
How to remove the package. The body is optional; without it the package ends now.
atPeriodEnd?booleantrue ends it at the end of its paid period. Default: now.
falsereason?stringWhy it is removed, at most 200 characters. Kept as cancelReason.
length <= 200Removed, or marked to end. invoice is set only when the held renewal changed.
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 package after the remove.
curl -X POST 'https://payments.clocknext.com/api/v1/subscriptions/pur_ghi789/packages/cmwi3bgxx00088dm6svjsa3i1/remove' \ -H 'Content-Type: application/json' \ -d '{ "atPeriodEnd": true, "reason": "Customer asked to stop the booster"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Package marked for removal." }, "result": { "purchasePackage": { "id": "cmwi3bgxx00088dm6svjsa3i1", "packageId": "cmwi3bd3s00008dm6ogh2wkc4", "name": "Chat Booster", "status": "MARKED_FOR_CANCELLATION", "cost": 4.5, "entitlements": { "credits": [ { "id": "csmwfugghy00000006", "name": "Chat Credits", "quantity": 1000 } ], "outcomes": [], "units": [], "composites": [], "flatFee": 2 }, "startedAt": "2026-11-15T17:10:10.174Z", "endsAt": "2026-12-13T18:30:00.000Z", "endedAt": null, "endedReason": null, "cancelReason": "Customer asked to stop the booster", "notes": null, "invoiceId": "cmwi3bgyj000b8dm6e9gshf1t" }, "invoice": null }}Types
Every object type on this page, with its fields.
RemoveSubscriptionPackageInput
How to remove the package. The body is optional; without it the package ends now.
| Field | Type | Required | Description |
|---|---|---|---|
atPeriodEnd | boolean | no | true ends it at the end of its paid period. Default: now. |
reason | string | no | Why it is removed, at most 200 characters. Kept as cancelReason. |
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. |
PackageInvoice
The invoice a package write made or changed, with its pay link while it is open.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The invoice's id. |
invoiceNumber | string | yes | Its reference. |
status | InvoiceStatus | yes | Its status. PAID when it was recorded as paid. |
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. |
payUrl | string | null | yes | The hosted page where the customer pays it, while it is OPEN. Else null. |
PackageInvoice.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.
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).
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`.