Packages
Extra entitlements for one price, added to a customer's subscription. A package renews with the subscription on its plan's billing cycle until it is removed, and is always paid in advance. It has no billing cycle, billing mode or rollover of its own, never holds a wallet, and holds one flat fee at most. Each entitlement but a flat fee must be on the customer's plan as advance. Nothing is deleted — archive instead. Add and remove packages with the Subscriptions routes. See Packages.
Base URL https://payments.clocknext.com/api/v1
Lists your packages, oldest first. Pass active=true for the ones that can be added to a subscription.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
active?booleantrue returns only active packages.
Packages.
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 workspace's packages.
curl -X GET 'https://payments.clocknext.com/api/v1/packages?active=true'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "result": { "packages": [ { "id": "cmwi3bd3s00008dm6ogh2wkc4", "name": "Chat Booster", "description": "1,000 extra chat credits every billing cycle", "cost": 4.5, "currencyCode": "USD", "isActive": true, "entitlements": { "credits": [ { "id": "csmwfugghy00000006", "name": "Chat Credits", "quantity": 1000 } ], "outcomes": [], "units": [], "composites": [], "flatFee": 2 }, "createdAt": "2026-11-15T17:10:05.080Z", "updatedAt": "2026-11-15T17:10:05.903Z" }, { "id": "cmwi3bi7w000g8dm63vdvyhnt", "name": "Image Booster", "description": null, "cost": 4.75, "currencyCode": "USD", "isActive": true, "entitlements": { "credits": [ { "id": "csmwfugghy00000008", "name": "Image Credits", "quantity": 100 } ], "outcomes": [], "units": [], "composites": [], "flatFee": null }, "createdAt": "2026-11-15T17:10:11.708Z", "updatedAt": "2026-11-15T17:10:11.708Z" } ] }}Base URL https://payments.clocknext.com/api/v1
Creates a package: entitlements grouped by kind and its price (cost), paid in advance on the plan's billing cycle. Each entitlement but the flat fee must be on a customer's plan, as advance, before the package can be added.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
application/json- body
A new package with at least one entitlement. billingCycle, billingMode, rollover, currencyCode, isActive, subtotalUsd and priceAdjustment are a 400.
name*stringThe package's name. Must be unique in the workspace (409 if taken).
1 <= length <= 120description?|Optional note about the package.
length <= 500cost*numberThe package price per billing cycle of the plan, in USD.
0 <= valueentitlements*The package's entitlements, grouped by kind.
Package created.
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 new package.
curl -X POST 'https://payments.clocknext.com/api/v1/packages' \ -H 'Content-Type: application/json' \ -d '{ "name": "Chat Booster", "description": "1,000 extra chat credits each cycle", "cost": 5, "entitlements": { "credits": [ { "id": "csmwfugghy00000006", "quantity": 1000 } ], "flatFee": 2 }}'{ "statusCode": 201, "statusDetail": { "status": "SUCCESS", "message": "Package created." }, "result": { "created": true, "package": { "id": "cmwi3bd3s00008dm6ogh2wkc4", "name": "Chat Booster", "description": "1,000 extra chat credits each cycle", "cost": 5, "currencyCode": "USD", "isActive": true, "entitlements": { "credits": [ { "id": "csmwfugghy00000006", "name": "Chat Credits", "quantity": 1000 } ], "outcomes": [], "units": [], "composites": [], "flatFee": 2 }, "createdAt": "2026-11-15T17:10:05.080Z", "updatedAt": "2026-11-15T17:10:05.080Z" } }}Base URL https://payments.clocknext.com/api/v1
Updates only the fields you send. entitlements is the complete new set; a group left out is empty. Without cost, new entitlements set the price to their list prices. Customers who have the package keep their copy.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringPackage id.
application/json- body
Only the fields you send change. entitlements is the complete new set. Without cost, new entitlements set the price to their list prices; an update without entitlements keeps the price. Customers who have the package keep their copy.
name?stringA new name. Must be unique in the workspace (409 if taken).
1 <= length <= 120description?|A new note. Send null to clear it.
length <= 500cost?numberA new price per billing cycle, in USD.
0 <= valueentitlements?The complete new set of entitlements, grouped by kind.
Package updated.
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 updated package.
curl -X PATCH 'https://payments.clocknext.com/api/v1/packages/cmwi3bd3s00008dm6ogh2wkc4' \ -H 'Content-Type: application/json' \ -d '{ "description": "1,000 extra chat credits every billing cycle"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Package updated." }, "result": { "updated": true, "package": { "id": "cmwi3bd3s00008dm6ogh2wkc4", "name": "Chat Booster", "description": "1,000 extra chat credits every billing cycle", "cost": 5, "currencyCode": "USD", "isActive": true, "entitlements": { "credits": [ { "id": "csmwfugghy00000006", "name": "Chat Credits", "quantity": 1000 } ], "outcomes": [], "units": [], "composites": [], "flatFee": 2 }, "createdAt": "2026-11-15T17:10:05.080Z", "updatedAt": "2026-11-15T17:10:05.860Z" } }}Base URL https://payments.clocknext.com/api/v1
Gets one package.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringPackage id.
The package.
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 with this id, in package.
curl -X GET 'https://payments.clocknext.com/api/v1/packages/cmwi3bd3s00008dm6ogh2wkc4'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Request processed successfully." }, "result": { "package": { "id": "cmwi3bd3s00008dm6ogh2wkc4", "name": "Chat Booster", "description": "1,000 extra chat credits each cycle", "cost": 5, "currencyCode": "USD", "isActive": true, "entitlements": { "credits": [ { "id": "csmwfugghy00000006", "name": "Chat Credits", "quantity": 1000 } ], "outcomes": [], "units": [], "composites": [], "flatFee": 2 }, "createdAt": "2026-11-15T17:10:05.080Z", "updatedAt": "2026-11-15T17:10:05.080Z" } }}Base URL https://payments.clocknext.com/api/v1
Archives a package: it can't be added to a subscription any more. Customers who have it keep it. Nothing is deleted.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringPackage id.
Package archived.
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 archived package.
curl -X POST 'https://payments.clocknext.com/api/v1/packages/cmwi3bd3s00008dm6ogh2wkc4/archive'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Package archived." }, "result": { "archived": true, "package": { "id": "cmwi3bd3s00008dm6ogh2wkc4", "name": "Chat Booster", "description": "1,000 extra chat credits every billing cycle", "cost": 4.5, "currencyCode": "USD", "isActive": false, "entitlements": { "credits": [ { "id": "csmwfugghy00000006", "name": "Chat Credits", "quantity": 1000 } ], "outcomes": [], "units": [], "composites": [], "flatFee": 2 }, "createdAt": "2026-11-15T17:10:05.080Z", "updatedAt": "2026-11-15T17:10:06.584Z" } }}Base URL https://payments.clocknext.com/api/v1
Restores an archived package: it can be added to subscriptions again.
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringPackage id.
Package unarchived.
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 restored package.
curl -X POST 'https://payments.clocknext.com/api/v1/packages/cmwi3bd3s00008dm6ogh2wkc4/unarchive'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Package restored." }, "result": { "unarchived": true, "package": { "id": "cmwi3bd3s00008dm6ogh2wkc4", "name": "Chat Booster", "description": "1,000 extra chat credits every billing cycle", "cost": 4.5, "currencyCode": "USD", "isActive": true, "entitlements": { "credits": [ { "id": "csmwfugghy00000006", "name": "Chat Credits", "quantity": 1000 } ], "outcomes": [], "units": [], "composites": [], "flatFee": 2 }, "createdAt": "2026-11-15T17:10:05.080Z", "updatedAt": "2026-11-15T17:10:07.259Z" } }}Types
Every object type on this page, with its fields.
Package
Entitlements and one price, added to a customer's subscription. It renews on the plan's billing cycle until removed, and is always paid in advance.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The package's id. |
name | string | yes | The package's name. Unique in the workspace. |
description | string | null | yes | Optional note about the package. null when not set. |
cost | number | yes | The package price for each billing cycle of the plan, in USD. |
currencyCode | string | yes | Always USD. |
isActive | boolean | yes | false once archived: it can't be added to a subscription. Read-only: use archive and unarchive. |
entitlements | PackageEntitlements | yes | What the package grants each cycle, grouped by kind. |
createdAt | string | yes | When the package was created. |
updatedAt | string | yes | When the package was last changed. |
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. |
CreatePackageInput
A new package with at least one entitlement. billingCycle, billingMode, rollover, currencyCode, isActive, subtotalUsd and priceAdjustment are a 400.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | The package's name. Must be unique in the workspace (409 if taken). |
description | string | null | no | Optional note about the package. |
cost | number | yes | The package price per billing cycle of the plan, in USD. |
entitlements | PackageEntitlementsInput | yes | The package's entitlements, grouped by kind. |
PackageEntitlementsInput
The package's entitlements, grouped by kind. A group left out is empty; each item appears once. wallet, the old flat list, and billingMode or rollover on an item are a 400.
| Field | Type | Required | Description |
|---|---|---|---|
credits | PackageEntitlementItemInput[] | no | The credits, as { id, quantity }. |
outcomes | PackageEntitlementItemInput[] | no | The outcomes, as { id, quantity }. |
units | PackageEntitlementItemInput[] | no | The units, as { id, quantity }. |
composites | PackageEntitlementItemInput[] | no | The composites, as { id, quantity }. |
flatFee | number | null | no | A flat fee in USD each cycle. Left out or null, none. |
PackageEntitlementItemInput
One credit, outcome, unit or composite to put in a package.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The credit's, outcome's, unit's or composite's own id. Active and in your workspace. |
quantity | integer | yes | Granted each cycle, a whole number above 0. |
name | string | no | Ignored, so an item from a GET can be sent back as it is. |
UpdatePackageInput
Only the fields you send change. entitlements is the complete new set. Without cost, new entitlements set the price to their list prices; an update without entitlements keeps the price. Customers who have the package keep their copy.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | A new name. Must be unique in the workspace (409 if taken). |
description | string | null | no | A new note. Send null to clear it. |
cost | number | no | A new price per billing cycle, in USD. |
entitlements | PackageEntitlementsInput | no | The complete new set of entitlements, grouped by kind. |