Billing & Usage
How Ductor treats money, budgets, and usage — the settled stage of the clearing lifecycle across four metering and pricing planes that must not be conflated.
Billing is the settled stage of the clearing lifecycle: what work cost, who pays, and what reverses when work is bad. Today that job is split across the four planes below, and Settlement as a single balanced-entry journal — one authoritative account of gross, fee, and net per unit of work — ships as an opt-in co-write over them. This page maps what charges today.
Ductor stores no tenant subscriptions, plans, statuses, or invoices. All of that lives in the external billing provider. The runtime exposes only a thin, read-only view: an "externally managed" flag, a customer-portal link, and a deployment default currency.
The dashboard billing view is a pointer to the provider, not a billing
system. BillingService.GetBillingSummary (GET /api/v2/billing/summary)
returns exactly that view — managed_externally is always true, and
balance_minor_units is always 0 (reserved; per-recipient prepaid balances
are tracked elsewhere and are not surfaced here). Full detail lives on the
provider integration page.
Four separate money/budget/usage concepts — do not conflate them
This section exists because several planes borrow overlapping vocabulary ("billing", "budget", "usage") while doing completely different jobs. Only concept (3) is true customer billing; (2) and (4) merely reuse the words.
- Durable usage metering + budget policies — tenant-scoped, append-only usage events with warn / shadow-deny / hard-deny caps → Usage metering.
- Per-recipient commerce pricing — charges, credits, and budgets per lead, plus the auction settlement pricing ledger → Commerce & pricing.
- Provider wallet/charge billing — recipient-scoped prepaid wallets with real money movement, and metered-usage invoicing (both experimental and opt-in) → Provider integration.
- AI LLM in-process spend guards — per-process
ai.routing.*cost caps, a distinct mechanism → AI → Inference proxy.
Billing summary
The billing summary is deliberately minimal. The domain type carries only four
facts: whether billing is managed externally, where the customer portal is, the
configured default currency (ISO 4217, lowercased, e.g. usd), and a balance
field that returns zero.
curl -s http://localhost:8080/api/v2/billing/summary \
-H "X-Tenant-ID: $DUCTOR_TENANT_ID"The endpoint requires tenant:read authorization (production auth is covered in
Auth; in local dev, auth is disabled and requests carry only the
X-Tenant-ID header). Because Ductor has no plan-assignment API, subscription
state flows in from the provider — see Plans & entitlement
enforcement for how that lands as an entitlement fact.
Doc map
Plans & entitlement enforcement
A "plan" is not a separate system — it is an entitlement item. Tier ranks, enforcement postures, and how provider state becomes a plan tier.
Usage metering
Tenant-scoped, append-only usage events with warn / shadow-deny / hard-deny budget caps enforced at connector admission.
Commerce & pricing
Per-recipient charges, credits, and budgets per lead, plus the auction settlement pricing ledger.
Provider integration
The external billing summary, recipient prepaid wallets, metered-usage invoicing, and how subscription state populates entitlement sources.
Related
Concepts → Entitlements
The plan/quota model: what a tenant is provisioned for and how limits are enforced on the hot path.
Auth → Entitlements
The capability plane and its report / strict / off enforcement postures.
Reference → Configuration
Entitlement and rate-limit config keys.
Operations → Backup & restore
Point-in-time recovery runbook, including the provider ledger tables.
Publishers
Manage traffic sources and lead vendors — publisher CRUD, pause/resume ingestion, volume caps and quality thresholds, per-publisher pricing, and delivery statistics.
Plans, Entitlements & Clearing Limits
A plan is not a separate system — it is an entitlement item; how tier gating, enforcement postures, and provider-driven lifecycle add to the entitlement model.