Create a checkout
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).
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
application/json- body
customerId?stringThe customer, by Clocknext id. Or send externalId; if both are sent, customerId wins.
externalId?stringThe customer, by your own id.
planId*stringThe plan to buy. Any active plan.
returnUrl?stringWhere to send the customer after paying: an absolute http(s) address, used as given. Optional.
uriNothing to pay — the plan was switched at once.
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 plan was switched at once; no link.
curl -X POST 'https://payments.clocknext.com/api/v1/checkout' \ -H 'Content-Type: application/json' \ -d '{ "customerId": "cmgcust0001", "planId": "cmgplan0pro", "returnUrl": "https://app.northwindtraders.com/billing"}'{ "statusCode": 201, "statusDetail": { "status": "SUCCESS", "message": "Checkout created." }, "result": { "id": "cmhcheckout0001", "url": "https://payments.clocknext.com/checkout/Y21oY2hlY2tvdXQwMDAxAbCdEfGhIjKlMnOpQrStUv", "expiresAt": "2026-10-30T10:00:00.000Z" }}Types
Every object type on this page, with its fields.
CheckoutCreateInput
| Field | Type | Required | Description |
|---|---|---|---|
customerId | string | no | The customer, by Clocknext id. Or send externalId; if both are sent, customerId wins. |
externalId | string | no | The customer, by your own id. |
planId | string | yes | The plan to buy. Any active plan. |
returnUrl | string | no | Where to send the customer after paying: an absolute http(s) address, used as given. Optional. |
CheckoutSwitched
| Field | Type | Required | Description |
|---|---|---|---|
status | "SWITCHED" | yes | The plan had nothing to pay and no card to save, so it is already active. |
purchaseId | string | yes | The new purchase. |
plan | object | yes | The plan the customer is on now. |
CheckoutSwitched.plan
The plan the customer is on now.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The plan's id. |
name | string | yes | The plan's name. |
Cancel a purchase POST
Cancels the purchase now: it becomes `CANCELLED`, its `OPEN` invoices are voided, and usage not billed yet gets a final invoice. This also completes a subscription marked for cancellation. A purchase already cancelled answers `200` again. To cancel at the period end, use [Cancel a subscription](/docs/api-reference/subscriptions/cancelSubscription).
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).