Identify the ClockNext organisation behind the configured API key, and — crucially — whether it is a 'sandbox' (a disposable staging twin) or the 'live' organisation. Call this FIRST to confirm you are pointed at the intended workspace before recording any real usage.

List the models the organisation has enabled, with their USD prices per 1,000,000 tokens. Use a returned modelId as the model when verifying or recording usage. Pass active=true to see only models that can be metered right now.

Validate and PRICE a usage signal WITHOUT recording it — a dry run. Returns the projected usage log (cost, credits drawn, applied rules) so you can confirm the customer, model, and plan are wired up correctly before sending real traffic. Records nothing and never bills.

Record ONE real usage signal — it is metered and billed. Prices the tokens against the model and the customer's plan and returns the resulting usage log. Pass an idempotencyKey to make retries safe (a repeat with the same key returns the original result instead of double-recording). For a no-op preflight, use clocknext_verify_signal instead.

Search ClockNext's official documentation and get back the most relevant pages (title, URL, and a snippet). ClockNext is a usage-based billing platform: you meter product/AI usage, price it against plans and units, and bill customers for it.

ALWAYS prefer this over answering from memory — the docs are the source of truth and are more current than your training data. Call it before you explain a ClockNext concept, design an integration, or reach for any other ClockNext tool.

Docs come in three kinds. Work through them in order:

1. concept — WHAT things are and HOW ClockNext works: the domain model (plans, units, outcomes, credits, customers, invoices, wallet/balances) and billing behaviour. START HERE to get context. If a term is unfamiliar, search concept first before touching any reference.

2. api — the language-agnostic REST API reference (endpoints, params, request/response shapes). Use this to actually implement or call ClockNext from ANY language.

3. javascript — reference for the official JavaScript/TypeScript SDK (@clocknext/sdk), a typed convenience wrapper over the same REST API.

IMPORTANT — the SDK is JavaScript/TypeScript ONLY, and the docs will NOT tell you this. If the customer's codebase is not JS/TS (e.g. Python, Go, Ruby, PHP, Rust, Java, C#), do NOT use the javascript kind — use api and integrate against the REST API directly. Only choose javascript once you have confirmed the target codebase is JS/TS.

Omit kind to search everything. Typical flow: search concept to understand the task, then search api (or javascript for a JS/TS codebase) for the exact reference you need to write code.

Read the FULL contents of a single ClockNext docs page as Markdown. Use this right after clocknext_search_docs: pass the url of a promising search result to read the whole page — endpoints, parameters, request/response fields, and code samples that the search snippet leaves out.

clocknext_search_docs finds WHICH page you need (title + url + a short snippet); this tool reads THAT page in full. A snippet is enough to choose a page, never enough to implement against — when you need exact field names, types, or the request body, call this.

ALWAYS use this for ClockNext docs instead of any external web-fetch/browser tool: it returns the authoritative page verbatim, whereas an external fetch routes the page through a summariser that can silently drop details (e.g. required fields like agentKey/idempotencyKey).

List the organisation's billing plans (id, name, billing cycle, price, active). Use it to find a plan id or to see what's on offer. Pass active=true for only sellable plans.

Get one plan in full by id — its entitlement components (wallet/credit/outcome/unit/flat), billing cycle, currency and active state.

Create a billing plan. A plan bundles one or more entitlement components: WALLET (prepaid USD balance, debited at raw model cost — NO margin), FLAT (one-off fee), or CREDIT/OUTCOME/UNIT entitlements that reference an existing credit/outcome/unit BY ID — so create those first (clocknext_create_credit / _outcome / _unit) and list them to get ids. Each component has a billingMode: ADVANCE (up-front, needs amount/quantity) or ARREAR (metered). FREE plans must be ADVANCE-only with no FLAT component. PREFER the dashboard plan builder (https://payments.clocknext.com/plans) — it previews what a customer pays; use this tool as the fallback. This creates a real, sellable plan — get the pricing right before you create it.

Replace a plan by id with a COMPLETE new definition (same shape as create — a full rewrite, not a patch; omitted fields are dropped). Changes the plan going forward; customers already on it keep their terms. Read it first with clocknext_get_plan, edit, then send the whole thing back.

Deactivate a plan in your catalogue (sets isActive→false) — ClockNext's soft archive, NOT a delete. The plan and its history are kept and customers already on it are unaffected; it simply becomes unsellable and drops out of active lists. Reversible: reactivate via clocknext_update_plan with isActive:true (a full rewrite) — there is no separate un-archive tool. Use ONLY to retire a plan you no longer sell. This does NOT delete anything and is unrelated to cancelling a customer's purchase or ending a subscription.

List the organisation's credit types (id, name, agentKey, price, active). Use it to find a credit id to reference from a plan's CREDIT component.

Get one credit type in full by id — pricing, token mapping and active state.

Create a credit type — a token-metered entitlement your product draws down against its agentKey. Pricing is MODEL-GROUNDED: give models (a mixer of enabled catalog model(s) + avg tokens + input/output/cache split) and a marginPercent; the tool reads live model prices and COMPUTES the base price + price-per-credit — you never hand-type a price, so a credit can't be mispriced or grounded in a disabled model. First-class alternative: create/price it in the dashboard (https://payments.clocknext.com/credits) — its live mixer preview is clearer and records the full per-model bundle; use this tool as the fallback (it stores the computed price only). A plan grants the credit via a CREDIT component referencing its id.

Replace a credit by id with its COMPLETE new definition — a full rewrite, NOT a partial patch (omitted fields are cleared). Pricing is re-grounded from the models mixer you pass (same as create). To only flip active state, pass the current values plus isActive. Read the current credit with clocknext_get_credit first. Changing agentKey re-points which runtime signals map here — do it deliberately.

Deactivate a credit TYPE in your catalogue (sets isActive→false) — ClockNext's soft archive, NOT a delete. The credit and its history are kept; recorded usage and any plan already granting it keep working (update those plans with clocknext_update_plan to stop offering it). It simply can't be added to new plans and drops out of active lists. Reversible: reactivate via clocknext_update_credit with isActive:true (a full rewrite) — there is no separate un-archive tool. Use ONLY to retire a credit you no longer sell. This does NOT delete anything and is unrelated to archiving a customer, ending a purchase, or clearing a balance.

List the organisation's outcome types (id, name, price, active). Use it to find an outcome id to reference from a plan's OUTCOME component.

Get one outcome type in full by id — its steps plus in-flight/completed stats.

Create an outcome type — a multi-step LLM deliverable billed per COMPLETED outcome. Each of the 1–50 steps has its own agentKey and its own model mixer (models): the tool computes each step's base cost from live model prices, sums them, and applies marginPercent. Outcomes are for token-priced, multi-LLM-step deliverables; a fixed-cost / non-LLM event (e.g. an upload or export) belongs in a UNIT, not an outcome step. First-class alternative: build it in the dashboard (https://payments.clocknext.com/outcomes) — clearer per-step pricing preview; use this tool as the fallback. A plan grants it via an OUTCOME component referencing its id.

Replace an outcome by id with its COMPLETE new definition — a full rewrite, NOT a partial patch (omitted steps/fields are dropped). Each step's price is re-grounded from its models mixer (same as create). Read the current outcome with clocknext_get_outcome first. Step agent keys are the runtime binding — change them deliberately.

Deactivate an outcome TYPE in your catalogue (sets isActive→false) — ClockNext's soft archive, NOT a delete. The outcome, its steps, and any in-flight or completed history are kept; existing plans and outcomes already in progress are unaffected. It simply can't be added to new plans and drops out of active lists. Reversible: reactivate via clocknext_update_outcome with isActive:true (a full rewrite) — there is no separate un-archive tool. Use ONLY to retire an outcome you no longer sell. This does NOT delete anything and is unrelated to archiving a customer or ending a purchase.

List the organisation's unit types (id, name, pricing type, active). Use it to find a unit id to reference from a plan's UNIT component.

Get one unit type in full by id — pricing type, flat price or tiers, plus usage stats.

Create a unit type: a metered usage unit reported against a lowercased stable agentKey (the key you send when recording unit usage) — its durable identity, unique org-wide. Units are for FIXED-COST / non-LLM events (an upload, an export, a seat) — one event = one unit, no tokens. Price it FLAT (a single flatPrice per event, default 0) or tiered — pricingType SLAB or VOLUME with tiers (1–50, ordered; only the last tier may have upTo:null). PREFER the dashboard (https://payments.clocknext.com/units) for the live price preview; use this tool as the fallback. A plan meters it via a UNIT component referencing this unit's id.

Replace a unit by id with its COMPLETE new definition — a full rewrite, NOT a partial patch: any optional field you omit (description, tiers, flatPrice) is CLEARED, not left as-is. Read the current unit with clocknext_get_unit first, edit, then send the whole object back. Changing agentKey re-points which runtime signals map here — do it deliberately.

Deactivate a unit TYPE in your catalogue (sets isActive→false) — ClockNext's soft archive, NOT a delete. The unit and its recorded usage are kept; existing plans metering it keep working. It simply can't be added to new plans and drops out of active lists. Reversible: reactivate via clocknext_update_unit with isActive:true (a full rewrite) — there is no separate un-archive tool. Use ONLY to retire a unit you no longer sell. This does NOT delete anything and is unrelated to archiving a customer or ending a purchase.

Create a ClockNext customer — the entity you bill (maps to one of your end-users / tenants / organisations). name and email are required; everything else is optional profile. Returns the customer with its ClockNext id, which you pass as customerId when subscribing to a plan (clocknext_create_purchase) and when recording usage (clocknext_record_usage).

Fetch one customer by ClockNext id.

List / search the org's customers, most-recent first (cursor-paginated). Use it to find a customer id or check whether one already exists before creating.

Read back a customer's recent usage logs (most recent first). Use it to CONFIRM a signal landed — e.g. after running the product's code so it fires a real signal, check the event shows up here with the expected model, tokens, and cost. For a signal you fire directly, clocknext_record_usage already returns the priced log inline, so this is mainly for signals sent by the running codebase.

Fetch a customer's current wallet / credit / outcome / unit balances. Use it to confirm a purchase granted the expected entitlements, or that a test signal drew the balance down as expected.

Fetch a customer's current active plan (from their purchase). Use it to confirm a customer is subscribed to the plan you expect before firing a test signal.

Subscribe a customer to a plan (a 'purchase') — this is what activates the plan for that customer. A usage signal only prices if the customer has an active plan whose components match the meter (credit / outcome / unit), so do this after clocknext_create_customer + clocknext_create_plan. Used to wire up a dummy customer before firing test signals.

Bulk-create ClockNext customers in ONE request — for backfilling an existing user base. Pass an array of customers (each needs name + email; up to 200 per call). The whole batch goes to the server in a single call and comes back with a PER-ROW result — created id, or an error — so one duplicate/bad row never aborts the batch. Match results back to your users by email. Runs against a private, MCP-only bulk endpoint (no SDK / public API); for a larger base, call it again in ≤200-row chunks.

Enable a model for the organisation so usage can be metered against it — afterwards its modelId is valid in clocknext_record_usage / clocknext_verify_signal and appears in clocknext_list_models. Only models in ClockNext's pricing catalog can be added, AUTOPRICED: give the provider and model (its catalog id) and ClockNext copies that model's input/output/cache prices from the catalog — you never set prices here. If the catalog has no price for it, the model is still enabled but meters at $0, and you must set its price manually on the Models page (the tool returns that link and a warning). A model or provider that isn't in the catalog can't be added — check clocknext_list_models first.