# Settlement (/docs/primitives/settlement)



**Settlement** is the money movement that closes the <Term name="Work" /> — a
charge, a credit, or a claw-back. Today it reads as ledger transactions plus
returns-driven reversals (<TechnicalName public="Settlement" api="ledger transactions" />);
new work also settles on the dedicated balanced-entry work-settlement journal.

Wallets support prepay with auto-top-up; postpay accumulates into invoices. Usage
is metered across everything — routing decisions, connector actions, workflow
steps, tool calls, tokens in and out — denominated to the micro-unit. Because
work can be bad, settlement is reversible by contract: within a
<Term name="Warranty" /> window the buyer can return the work, triggering an
automatic credit and optional re-routing.

<Fact label="Status">
  shipping — the ledger, wallets, usage invoicing, and returns exist today; the
  balanced-entry journal in integer micro-units co-writes alongside them, enabled
  per deployment behind a settlement flag.
</Fact>

## Settlement states [#settlement-states]

A market settlement moves through `MarketSettlementStatus`:

<StateGrid label="Settlement states">
  <StateCard title="pending → held" code="MarketSettlementStatus" tone="gold">
    Funds are reserved when a winner is committed.
  </StateCard>

  <StateCard title="held → committed" code="MarketSettlementStatus" tone="commit">
    Captured once the work completes successfully.
  </StateCard>

  <StateCard title="failed · cancelled" code="MarketSettlementStatus" tone="halt">
    Released without capture when the work does not clear.
  </StateCard>
</StateGrid>

<Fact label="Why a separate journal">
  New work settles on a balanced-entry journal in integer micro-units, where
  every committed transaction nets to zero per currency. The existing float-based
  lead ledger and the Stripe tables become payment adapters — money integrity is
  a property of the journal, not a convention.
</Fact>

<Fact label="What the journal enforces">
  Zero-sum is enforced by the database itself at commit, entries are append-only,
  and corrections are always new compensating transactions. Each settlement is
  identified per unit of work and party, transitions under optimistic locking,
  and every posting carries an idempotency fingerprint — a replay converges on
  the original, and a reused key with different money fails loudly. Committed
  journal transactions flow into the work's <Term name="Receipt" /> as its
  settlement evidence.
</Fact>

## Where to go deeper [#where-to-go-deeper]

<Cards>
  <Card title="The settlement journal" href="/docs/billing/settlement-journal">
    Balanced-entry money movement in depth — accounts, posting rules, and what the database enforces.
  </Card>

  <Card title="Billing & commerce" href="/docs/billing/commerce">
    Pricing, wallets, and how charges are collected.
  </Card>

  <Card title="Usage metering" href="/docs/billing/usage-metering">
    What is metered, and in what units.
  </Card>

  <Card title="Warranty" href="/docs/primitives/warranty">
    The window in which a settlement reverses.
  </Card>
</Cards>