Add packages to a subscription
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.
Base URL https://payments.clocknext.com/api/v1
apiKeyAuthorizationBearer <cnk_…>Organisation-scoped key from Settings → API Keys.
id*stringThe purchase id of the subscription.
application/json- body
The packages to add, on one invoice. Each must be active, with its entitlements on the plan as advance.
packageIds*array<string>1 to 10 package ids, each once. The answer keeps this order.
1 <= items <= 10recordAsPaid?Records the invoice as paid outside Clocknext, so the packages start at once.
notes?stringA reference or PO number, at most 500 characters. Kept on each package and shown on the invoice.
length <= 500idempotencyKey?string1–255 characters. A repeat with the same packages answers the first attach.
1 <= length <= 255A repeat of an earlier attach with the same idempotencyKey. Nothing is written.
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 earlier attach.
curl -X POST 'https://payments.clocknext.com/api/v1/subscriptions/pur_ghi789/packages' \ -H 'Content-Type: application/json' \ -d '{ "packageIds": [ "cmwi3bd3s00008dm6ogh2wkc4" ], "notes": "PO-1234", "idempotencyKey": "order_5521"}'{ "statusCode": 200, "statusDetail": { "status": "SUCCESS", "message": "Packages already added with this idempotency key." }, "result": { "purchasePackages": [ { "id": "cmwi3bgcq00038dm6ma9fvga0", "packageId": "cmwi3bd3s00008dm6ogh2wkc4", "name": "Chat Booster", "status": "SCHEDULED", "cost": 4.5, "entitlements": { "credits": [ { "id": "csmwfugghy00000006", "name": "Chat Credits", "quantity": 1000 } ], "outcomes": [], "units": [], "composites": [], "flatFee": 2 }, "startedAt": null, "endsAt": null, "endedAt": null, "endedReason": null, "cancelReason": null, "notes": "PO-1234", "invoiceId": "cmwi3bgdn00068dm6ur3zcxdl" } ], "invoice": { "id": "cmwi3bgdn00068dm6ur3zcxdl", "invoiceNumber": "INV-0162", "status": "OPEN", "amount": 4.5, "creditedUsd": 0, "balanceAppliedUsd": 0, "amountDueUsd": 4.5, "payUrl": "https://payments.clocknext.com/pay/Y213aTNiZ2RuMDAwNjhkbTZ1cjN6Y3hkbA.hUYLMVFHFelFMa6iApZjcvIGL3kYF8w7q2vaVWJA5wo" }, "replayed": true }}Types
Every object type on this page, with its fields.
AddSubscriptionPackagesInput
The packages to add, on one invoice. Each must be active, with its entitlements on the plan as advance.
| Field | Type | Required | Description |
|---|---|---|---|
packageIds | string[] | yes | 1 to 10 package ids, each once. The answer keeps this order. |
recordAsPaid | object | no | Records the invoice as paid outside Clocknext, so the packages start at once. |
notes | string | no | A reference or PO number, at most 500 characters. Kept on each package and shown on the invoice. |
idempotencyKey | string | no | 1–255 characters. A repeat with the same packages answers the first attach. |
AddSubscriptionPackagesInput.recordAsPaid
Records the invoice as paid outside Clocknext, so the packages start at once.
| Field | Type | Required | Description |
|---|---|---|---|
mode | "CASH" | "BANK_TRANSFER" | "WIRE_TRANSFER" | "CARD" | "CHEQUE" | "UPI" | "OTHER" | yes | How it was paid. |
reference | string | no | Your reference for the payment, at most 200 characters. |
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. |
PackageInvoice
The invoice a package write made or changed, with its pay link while it is open.
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | The invoice's id. |
invoiceNumber | string | yes | Its reference. |
status | InvoiceStatus | yes | Its status. PAID when it was recorded as paid. |
amount | number | yes | The invoice total in USD, tax included. |
creditedUsd | number | yes | All credit notes on it, in USD, tax included. |
balanceAppliedUsd | number | yes | What the customer's invoice balance paid, in USD. |
amountDueUsd | number | yes | What is still owed, in USD. 0 unless it is OPEN. |
payUrl | string | null | yes | The 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.
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.
Remove a package from a subscription POST
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`.