ClocknextClocknextHelp
DocumentationAPI ReferenceMCP Tools
Dashboard
What is Clocknext?Getting started

Customers

CustomersCustomer detail

Billing

PurchasesSubscriptionsPackagesInvoicesPaymentsCredit NotesRefunds

Tracking

SignalsRevenue dashboardCustomer Portal

Settings

Profile settingsOrganisation settingsTeam MembersModelsTaxesIntegrationsAPI KeysWebhooks

Documentation

Packages

Sell extra entitlements on top of a Customer's Plan — set up a package once, add it to a subscription, and remove it now or at the end of the paid period.

A package is one or more entitlements and one price, set up like a Plan and added to a Customer's subscription. For example, a "Chat Booster" that gives 1,000 extra chat credits and a $2 flat fee for $5. Once added, it renews with the subscription until it is removed.

How a package works

  • Paid in advance, on the Plan's cycle. A package has no billing cycle of its own: it is billed with the subscription's Plan, at the start of each cycle. It has no billing mode either: it is always advance.
  • It adds to the Plan's entitlements. Each entitlement of a package, except a flat fee, must be on the Customer's Plan as advance (not metered). Its grant is added to the same balance, and it rolls over like that entitlement on the Plan. A package can hold credits, outcomes, units, composites and one flat fee. It never holds a wallet.
  • One price. You set the package price (cost) for each billing cycle of the Plan, in USD.
  • Customers keep their copy. When a package is added, the subscription keeps a copy of its name, price and entitlements. Editing or archiving the package later changes nothing for the Customers who have it.
  • Nothing is deleted. Archive a package to stop adding it, and unarchive it to sell it again.

Set up the catalog

Create a package with its entitlements, grouped by kind: credits, outcomes, units and composites, each a list of { id, quantity } (the credit's, outcome's, unit's or composite's own id), and an optional flatFee in USD. A group left out is empty. cost, the package price, is required. See Packages API.

curl -X POST https://payments.clocknext.com/api/v1/packages \
  -H "Authorization: Bearer $CLOCKNEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Chat Booster",
    "cost": 5,
    "entitlements": {
      "credits": [{ "id": "csmwfugghy00000006", "quantity": 1000 }],
      "flatFee": 2
    }
  }'

Every answer shows all the groups: an empty list, and flatFee: null when there is none. An item in an answer also has the entitlement's name; it is ignored in a body, so you can send an answer back.

An update is partial. When you send entitlements, it is the complete new set; sent without cost, the price becomes their list prices. An update that sends neither keeps the price. A body with billingCycle, billingMode, rollover, isActive, subtotalUsd, priceAdjustment or a wallet group is a 400.

Add packages to a subscription

Add 1 to 10 packages to a running subscription in one call. Clocknext issues one invoice, with one line per package at its full price, and returns its pay link (invoice.payUrl).

  • Until the invoice is paid, each package is SCHEDULED and grants nothing.
  • When it is paid, the packages are ACTIVE and their grants are added to the Customer's balances.
  • When your organization uses the invoice balance for new invoices, the Customer's invoice balance pays the invoice first. If it covers the whole amount, the invoice comes back PAID with no payUrl and the packages are ACTIVE at once. If it covers part, the invoice stays OPEN for the rest.
  • With recordAsPaid (a payment made outside Clocknext), the invoice is recorded as paid and the packages are ACTIVE at once. The invoice balance is not used.
  • The optional notes (a reference or PO number, at most 500 characters) is kept on each package of the add as notes and shown on the package invoice.
curl -X POST https://payments.clocknext.com/api/v1/subscriptions/cmwfwy4px000veqm6f12fgddc/packages \
  -H "Authorization: Bearer $CLOCKNEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "packageIds": ["cmwi3bd3s00008dm6ogh2wkc4"], "notes": "PO-1234", "idempotencyKey": "order_5521" }'

A package can't be added when the subscription is on hold, marked for cancellation, cancelled or on a free Plan (SUBSCRIPTION_NOT_ACTIVE), when the package is archived (PACKAGE_ARCHIVED), or when the Plan doesn't have one of its entitlements as advance (PACKAGE_ENTITLEMENT_NOT_ON_PLAN, PACKAGE_ENTITLEMENT_METERED). Send an idempotencyKey to retry safely: the same key with the same packages returns the first answer with replayed: true. See Add packages to a subscription.

The subscription lists its packages in packages, on Get a subscription and List subscriptions: the ones that are SCHEDULED, ACTIVE or MARKED_FOR_CANCELLATION, oldest first. Cancelled packages are left out.

Remove a package

Remove a package by the id of its entry in subscription.packages (not the catalog package id). It works like cancelling a subscription:

You sendWhat happens
NothingThe package ends now (CANCELLED, endedReason: "REMOVED"). What is left of it is taken back: its grant less what was used, the package used first. Nothing is refunded.
atPeriodEnd: trueThe package is MARKED_FOR_CANCELLATION: it keeps working until endsAt, the end of its paid period, and does not renew. Remove it again without atPeriodEnd to end it now.

While the subscription is on hold, the package ends now either way, and its line comes off the unpaid renewal invoice (same number and pay link). The answer's invoice is that renewal.

The optional reason is kept as the package's cancelReason.

A package that is not paid yet (SCHEDULED) can't be removed (PACKAGE_AWAITING_PAYMENT): void its invoice instead, and the package ends. See Remove a package from a subscription.

curl -X POST https://payments.clocknext.com/api/v1/subscriptions/cmwfwy4px000veqm6f12fgddc/packages/cmwi3bgxx00088dm6svjsa3i1/remove \
  -H "Authorization: Bearer $CLOCKNEXT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "atPeriodEnd": true, "reason": "Customer asked to stop the booster" }'

A package that ends is CANCELLED, and endedReason says why:

endedReasonWhy it ended
REMOVEDIt was removed now, or its endsAt was reached at the renewal after a removal with atPeriodEnd.
INVOICE_VOIDEDIts unpaid invoice was voided, by hand or by the daily run.
PLAN_CHANGEDThe Customer moved to another Plan.
SUBSCRIPTION_CANCELLEDThe subscription was cancelled, or its hold ran out.

Webhooks

EventTriggered when
package.addedA package becomes active: its invoice is paid or recorded as paid. An unpaid attach is announced by invoice.created.
package.removal_scheduledA package is removed with atPeriodEnd: true.
package.endedA package ends. ended_reason says why.

Each event's data holds the customer, the subscription id and the package. See Webhooks.

Related

  • Subscriptions — what a package is added to.
  • Purchases — the Plan a subscription is for.
  • Invoices — the invoice that starts a package.
  • Packages API — list, create, update, archive and unarchive packages.

Subscriptions

See every billing period of your Customers' Plans, open one to see its Invoices and Payments, change its plan, or cancel it with or without a refund.

Invoices

Review the Invoices raised from Purchases, record payment, share a payment link, or void an Invoice.

On this page

How a package worksSet up the catalogAdd packages to a subscriptionRemove a packageWebhooksRelated