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
SCHEDULEDand grants nothing. - When it is paid, the packages are
ACTIVEand 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
PAIDwith nopayUrland the packages areACTIVEat once. If it covers part, the invoice staysOPENfor the rest. - With
recordAsPaid(a payment made outside Clocknext), the invoice is recorded as paid and the packages areACTIVEat 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 asnotesand 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 send | What happens |
|---|---|
| Nothing | The 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: true | The 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:
endedReason | Why it ended |
|---|---|
REMOVED | It was removed now, or its endsAt was reached at the renewal after a removal with atPeriodEnd. |
INVOICE_VOIDED | Its unpaid invoice was voided, by hand or by the daily run. |
PLAN_CHANGED | The Customer moved to another Plan. |
SUBSCRIPTION_CANCELLED | The subscription was cancelled, or its hold ran out. |
Webhooks
| Event | Triggered when |
|---|---|
package.added | A package becomes active: its invoice is paid or recorded as paid. An unpaid attach is announced by invoice.created. |
package.removal_scheduled | A package is removed with atPeriodEnd: true. |
package.ended | A 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.