Get a subscription
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."
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringThe purchase id of the subscription.
The subscription.
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 subscription of this purchase, in subscription.
curl -X GET 'https://payments.clocknext.com/api/v1/subscriptions/pur_ghi789'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "result": { "subscription": { "purchaseId": "cmvgvkmxz002h08l2h2i1dnsr", "customerId": "cmvgva5po000c07iir1vtn8vl", "planId": "cmvgvg2yq000s08l21gkr472h", "subscriptionNumber": "SUB-001", "status": "ACTIVE", "startsAt": "2026-10-20T16:06:35.316Z", "periodStart": "2026-10-20T00:00:00.000Z", "periodEnd": "2026-11-20T00:00:00.000Z", "nextRenewalDate": "2026-11-20T00:00:00.000Z", "holdEndsAt": null, "cancelRequestedAt": null, "endsAt": null, "cancelReason": null, "packages": [ { "id": "cmwi3bgxx00088dm6svjsa3i1", "packageId": "cmwi3bd3s00008dm6ogh2wkc4", "name": "Chat Booster", "status": "ACTIVE", "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": null, "endedAt": null, "endedReason": null, "cancelReason": null, "notes": null, "invoiceId": "cmwi3bgyj000b8dm6e9gshf1t" } ], "periods": [] } }}Types
Every object type on this page, with its fields.
SubscriptionDetail
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. |
periods | Subscription[] | yes | The periods it renewed out of (RENEWED), newest first. |
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. |
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. |
List subscriptions GET
Your customers' subscriptions: one row per period, newest purchase first, the running period before the ones it renewed from. A subscription is addressed by its `purchaseId`. Paged by purchase with `limit` and `cursor`; see [Paginating results](/docs/api-reference/pagination).
Cancel a subscription POST
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.