ClocknextClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard

Get started

OverviewQuickstart

Good to know

Response formatHandling errorsPaginating resultsSending data reliablyYour own customer idsWebhooks

API reference

Signals

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POSTList Customer Usage Log GETLook Up Usage Logs by ID GET

Deprecated

Record credit POSTRecord outcome POSTComplete outcome POSTRecord wallet POSTRecord unit POSTComplete composite POSTList raw signals GETRetry signals POST

Customers

List customers GETCreate a customer POSTGet a customer GETUpdate a customer PATCHDelete a customer DELETEGet a customer's balances GETGet a customer's wallet ledger GETSet a customer's low-balance alert for wallet PUTGet a customer's current plan GETChange a recurring grant PUTUpdate a customer's card POSTGet a customer's invoice balance GETAdjust a customer's invoice balance POST

Deprecated

List Customer Usage Log GETLook Up Usage Logs by ID GET

Manage

Manage a customer's credit balance POSTManage a customer's outcome balance POSTManage a customer's unit balance POSTManage a customer's composite balance POSTManage a customer's wallet balance POST

Members

List a customer's members GETAdd a member POSTUpdate a member PATCHRemove a member DELETE

Plans and Entitlements

PlansPackagesCreditsOutcomesUnitsComposites

Taxes

List taxes GETCreate a tax POSTGet a tax GETUpdate a tax PATCH

Purchases

List purchases GETCreate a purchase POSTGet a purchase GETUpdate a purchase's auto-payment setting PATCHCancel a purchase POST

Checkout

Create a checkout POST

Subscriptions

List subscriptions GETGet a subscription GETCancel a subscription POSTAdd packages to a subscription POSTRemove a package from a subscription POST

Plan changes

List plan changes GETPreview a plan change POSTChange a customer's plan POSTGet a plan change GET

Invoices

List invoices GETGet an invoice GETMint a hosted pay link GETRecord a payment POST

Credit notes

List credit notes GETCreate a credit note POSTGet a credit note GETVoid a credit note POST

Refunds

List refunds GETRefund to the card POSTGet a refund GET

Payments

List payments GETGet a payment GET

Webhooks

Customer Portal

Mint a customer-portal access token POST

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

POST
/subscriptions/{id}/packages/{purchasePackageId}/remove

Authorization

apiKey
headerAuthorizationBearer <cnk_…>

Organisation-scoped key from Settings → API Keys.

Path Parameters

id*string

The purchase id of the subscription.

purchasePackageId*string

The id of the package on the subscription (PurchasePackage.id), not the catalog package id.

Request Body

application/json
  1. body
  1. body
  2. …

How to remove the package. The body is optional; without it the package ends now.

atPeriodEnd?boolean

true ends it at the end of its paid period. Default: now.

Defaultfalse
reason?string

Why it is removed, at most 200 characters. Kept as cancelReason.

Lengthlength <= 200

Response Body

Removed, or marked to end. invoice is set only when the held renewal changed.

application/json
  1. response
  1. response
  2. …
statusCode*integer

The 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"}'
Example Response
{  "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.

FieldTypeRequiredDescription
atPeriodEndbooleannotrue ends it at the end of its paid period. Default: now.
reasonstringnoWhy 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.

FieldTypeRequiredDescription
idstringyesThe id of the package on this subscription. Use it to remove the package.
packageIdstring | nullyesThe catalog package it was added from. null when that package is gone.
namestringyesThe package's name when it was added.
status"SCHEDULED" | "ACTIVE" | "MARKED_FOR_CANCELLATION" | "CANCELLED"yesSCHEDULED (invoice unpaid), ACTIVE, MARKED_FOR_CANCELLATION (ends at endsAt) or CANCELLED.
costnumberyesThe price for each billing cycle when it was added, in USD.
entitlementsPackageEntitlementsyesWhat it grants each cycle, grouped by kind.
startedAtstring | nullyesWhen it started (its invoice was paid). null while SCHEDULED.
endsAtstring | nullyesWhen it ends or ended, the end of its paid period when marked. Else null.
endedAtstring | nullyesWhen it ended. null unless CANCELLED.
endedReason"REMOVED" | "INVOICE_VOIDED" | "PLAN_CHANGED" | "SUBSCRIPTION_CANCELLED" | nullyesWhy it ended. null unless CANCELLED.
cancelReasonstring | nullyesThe reason sent with the remove. null when none.
notesstring | nullyesThe notes sent with the add, such as a reference or PO number. null when none.
invoiceIdstring | nullyesThe 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.

FieldTypeRequiredDescription
creditsPackageEntitlementItem[]yesThe credits and their quantities.
outcomesPackageEntitlementItem[]yesThe outcomes and their quantities.
unitsPackageEntitlementItem[]yesThe units and their quantities.
compositesPackageEntitlementItem[]yesThe composites and their quantities.
flatFeenumber | nullyesThe 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.

FieldTypeRequiredDescription
idstringyesThe credit's, outcome's, unit's or composite's own id.
namestringyesIts name.
quantityintegeryesHow many it grants each cycle.

PackageInvoice

The invoice a package write made or changed, with its pay link while it is open.

FieldTypeRequiredDescription
idstringyesThe invoice's id.
invoiceNumberstringyesIts reference.
statusInvoiceStatusyesIts status. PAID when it was recorded as paid.
amountnumberyesThe invoice total in USD, tax included.
creditedUsdnumberyesAll credit notes on it, in USD, tax included.
balanceAppliedUsdnumberyesWhat the customer's invoice balance paid, in USD.
amountDueUsdnumberyesWhat is still owed, in USD. 0 unless it is OPEN.
payUrlstring | nullyesThe 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`.