> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enfinitos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlement

> Verified activity in, finance out — the disciplined path from metered units to invoices and reconciliations.

Settlement is the layer that turns metered units into invoices,
reconciliations, and finance-grade reports. It is designed in from
the start so it doesn't have to be bolted on later under audit
pressure.

## What settlement consumes

Settlement consumes three things:

1. **Metering projections** for the period, from the
   [metering](/concepts/metering) layer.
2. **Contract terms** — price-per-unit, discounts, minima, caps,
   tiered structures.
3. **Adjustment events** — refunds, credits, manual corrections,
   each with their own audit record.

## Rate cards

On the live `/v1` surface, the price-per-unit contract term is a
**rate card**: the tenant's pricing policy, mapping each meter unit
type to an integer price per unit in minor currency units
(gross = unit count × `pricePerUnitCents`; 0 means contractually
free). Cards are **currency-pinned** and targeted by substrate,
counterparty, and scope. Settlement rules decide who gets what share
of a meter's gross; the rate card decides what the gross **is**.

Cards share the settlement-rule lifecycle — `DRAFT`,
`PENDING_APPROVAL`, `SCHEDULED`, `ACTIVE`, `SUPERSEDED`, `CANCELLED`
— so both pricing planes go through the same explicit approval step
before they move real money. When several cards are ACTIVE, the
engine selects per meter by specificity (counterparty > substrate >
scope), and a tenant's own cards always outrank the platform
default.

| Method + path                           | Purpose                                                                       |
| --------------------------------------- | ----------------------------------------------------------------------------- |
| `GET /v1/rate-cards`                    | List your cards, the platform default, and the effective card id.             |
| `POST /v1/rate-cards`                   | Create a card (`label` + `prices`); DRAFT unless `activateOnCreate`.          |
| `POST /v1/rate-cards/{cardId}/activate` | Approve a card into ACTIVE — or SCHEDULED when `activeFrom` is in the future. |

## What settlement produces

For each tenant × counterparty × period, settlement produces:

* A **reconciliation document** with the metered units, the
  contractual rate card, the resulting line items, and the totals.
* A **proof-pack appendix** — the reconciliation is embedded in
  the relevant proof packs so the auditor can re-run it.
* An **invoice draft** — surfaced into the operator dashboard for
  human review before issue.

## What the auditor checks

The auditor re-runs settlement reconciliation from the metering
projection and the on-chain contract terms. The output must be
**bit-identical** — any divergence fails verification.

This is the property that makes settlement legally defensible:
nobody — not even EnfinitOS — can produce a settlement number that
isn't reproducible from the underlying signed events.

## Adjustments

Adjustments don't mutate historical packs. They are issued as new
proof events, signed and chained, and they roll forward into the
next reconciliation. The audit trail of "we adjusted X for Y reason"
is preserved permanently.

## Delivery disputes

When a counterparty claims delivery fell short of contract ("you
billed 1M impressions, we saw 800k"), the disagreement runs as a
first-class **delivery dispute** with its own state machine and an
append-only timeline. The evidence bundle — proof packs, metering
snapshots, settlement applications — is frozen at open time, so both
sides argue over the same artifacts.

A dispute opens as `OPENED` and advances through `INVESTIGATING` →
`EVIDENCE_GATHERED` → `OPERATOR_RESPONDED` (stance + proposed
remedy) → `ADVERTISER_RESPONDED` (accept / reject / negotiate).
`RESOLVED` and `WITHDRAWN` are terminal; `ESCALATED` (mediation) is
not — an escalated dispute can still resolve, withdraw, or rejoin
negotiation.

Resolution closes the money loop: a `SETTLEMENT_ADJUSTMENT`
resolution builds the settlement-application **override** that
corrects the disputed attribution and appends it in the same atomic
write as the dispute transition — an adjustment event exactly like
the section above, never a mutation of history.

| Method + path                              | Purpose                                                                                |
| ------------------------------------------ | -------------------------------------------------------------------------------------- |
| `GET /v1/disputes`                         | List disputes with per-state counts (`state` filter).                                  |
| `POST /v1/disputes`                        | Open a dispute: disputed period, affected surface, claimed shortfall, evidence bundle. |
| `GET /v1/disputes/{disputeId}`             | Full record: evidence, responses, resolution, timeline.                                |
| `POST /v1/disputes/{disputeId}/transition` | Drive the non-terminal legs (`toState` + response payloads).                           |
| `POST /v1/disputes/{disputeId}/resolve`    | Terminal resolution — credit, makegood, settlement adjustment, no credit.              |
| `POST /v1/disputes/{disputeId}/withdraw`   | The original opener withdraws — terminal.                                              |
| `POST /v1/disputes/{disputeId}/escalate`   | Either party escalates to mediation.                                                   |

Delivery disputes are about settlement quantities. They are distinct
from rights [challenges](/concepts/rights-as-bounded-context), which
contest whether a right should exist at all.