# Billing & Usage (/docs/billing)



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 <Term name="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](/docs/billing/stripe) page.

<Callout title="Four separate money/budget/usage concepts — do not conflate them" type="warn">
  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.

  1. **Durable usage metering + budget policies** — tenant-scoped, append-only
     usage events with warn / shadow-deny / hard-deny caps →
     [Usage metering](/docs/billing/usage-metering).
  2. **Per-recipient commerce pricing** — charges, credits, and budgets per
     lead, plus the auction settlement pricing ledger →
     [Commerce & pricing](/docs/billing/commerce).
  3. **Provider wallet/charge billing** — recipient-scoped prepaid wallets with
     real money movement, and metered-usage invoicing (both experimental and
     opt-in) → [Provider integration](/docs/billing/stripe).
  4. **AI LLM in-process spend guards** — per-process `ai.routing.*` cost caps,
     a distinct mechanism → [AI → Inference proxy](/docs/ai/inference-proxy).
</Callout>

## Billing summary [#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.

```bash
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](/docs/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](/docs/billing/plans) for how that lands as an entitlement fact.

## Doc map [#doc-map]

<Cards>
  <Card title="Plans & entitlement enforcement" href="/docs/billing/plans">
    A "plan" is not a separate system — it is an entitlement item. Tier ranks,
    enforcement postures, and how provider state becomes a plan tier.
  </Card>

  <Card title="Usage metering" href="/docs/billing/usage-metering">
    Tenant-scoped, append-only usage events with warn / shadow-deny / hard-deny
    budget caps enforced at connector admission.
  </Card>

  <Card title="Commerce & pricing" href="/docs/billing/commerce">
    Per-recipient charges, credits, and budgets per lead, plus the auction
    settlement pricing ledger.
  </Card>

  <Card title="Provider integration" href="/docs/billing/stripe">
    The external billing summary, recipient prepaid wallets, metered-usage
    invoicing, and how subscription state populates entitlement sources.
  </Card>
</Cards>

## Related [#related]

<Cards>
  <Card title="Concepts → Entitlements" href="/docs/concepts/entitlements">
    The plan/quota model: what a tenant is provisioned for and how limits are
    enforced on the hot path.
  </Card>

  <Card title="Auth → Entitlements" href="/docs/auth/entitlements">
    The capability plane and its report / strict / off enforcement postures.
  </Card>

  <Card title="Reference → Configuration" href="/docs/reference/configuration">
    Entitlement and rate-limit config keys.
  </Card>

  <Card title="Operations → Backup & restore" href="/docs/operations/backup-restore">
    Point-in-time recovery runbook, including the provider ledger tables.
  </Card>
</Cards>