List subscriptions
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.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
customerId?stringRestrict results to this customer.
status?stringOnly rows with this status (any letter case).
"SCHEDULED""ACTIVE""MARKED_FOR_CANCELLATION""RENEWED""CANCELLED"limit?integerHow many PURCHASES on one page: default 50, maximum 50 (a bigger value is cut to 50). It counts purchases, not periods, so the rows of one purchase are never split across two pages. Zero, a negative number or a non-number is a 400.
1 <= value <= 5050cursor?stringThe nextCursor of the previous page (a purchase id). Omit it for the first page.
Subscriptions.
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 subscription periods.
curl -X GET 'https://payments.clocknext.com/api/v1/subscriptions?customerId=cus_abc123&status=ACTIVE&limit=50'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "result": { "subscriptions": [ { "purchaseId": "cmvgvksil005p08l2ggbacq1l", "customerId": "cmvgva5po000c07iir1vtn8vl", "planId": "cmvgvgfob001m08l2upi4aokj", "subscriptionNumber": "SUB-008", "status": "CANCELLED", "startsAt": "2026-10-20T00:00:00.000Z", "periodStart": null, "periodEnd": null, "nextRenewalDate": null, "holdEndsAt": null, "cancelRequestedAt": null, "endsAt": null, "cancelReason": "Created by mistake — customer stays on Pro", "packages": [] }, { "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": [] }, { "purchaseId": "cmvgvkptw004i08l2d8vveucu", "customerId": "cmvgv9650000407iigjb3lt2p", "planId": "cmvgvg38w001808l2j7k6ykx3", "subscriptionNumber": "SUB-005", "status": "SCHEDULED", "startsAt": "2026-11-03T00:00:00.000Z", "periodStart": null, "periodEnd": null, "nextRenewalDate": null, "holdEndsAt": "2026-11-10T00:00:00.000Z", "cancelRequestedAt": null, "endsAt": null, "cancelReason": null, "packages": [] }, { "purchaseId": "cmvgvkp6r004a08l22itk1bh6", "customerId": "cmvgv9elh000807iixkqqodos", "planId": "cmvgvg2dn000n08l23x83smgo", "subscriptionNumber": null, "status": "ACTIVE", "startsAt": "2026-10-20T00:00:00.000Z", "periodStart": null, "periodEnd": null, "nextRenewalDate": null, "holdEndsAt": null, "cancelRequestedAt": null, "endsAt": null, "cancelReason": null, "packages": [] } ], "nextCursor": null }}Types
Every object type on this page, with its fields.
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. |
Create a checkout POST
Returns a link (`url`, valid 24 hours) for a customer to buy a plan on a secure payment page, then sends them to `returnUrl`. **Nothing changes until they pay.** Act on the `subscription.activated` webhook, not the redirect. A plan with nothing to pay is switched at once (`200`, `status: SWITCHED`).
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."