# Organization statements

> Read what an organization was charged in a period, checked against the digest it arrived with.

Section: Synapse and Locus. Web page: https://docs.katara.com/products/billing-statements/

A statement answers one question: what did this organization spend between two
moments. It is worked out from the charge records every time you ask, so the
same period always gives the same answer, and a correction that lands later
changes the period it belongs to rather than leaving an old total behind.

Both ends of the period are yours to choose and both are required. The start is
included and the end is not, so two statements that meet at a boundary neither
overlap nor leave a gap. A period longer than 366 days is refused.

## What a line means

Each line is one purpose, in one environment, under one usage class, at one price:

- **Simulation** is a rehearsal. No money moves.
- **Test Compute** is real spending in a Test environment.
- **Live** is real spending in a Live environment.

Purposes are inference, tool, service, sandbox and evaluation, and they stay on
separate lines because they answer different questions about the same month.
A governed tool action is one tool unit and an evaluation case one evaluation
unit, and `actions` counts them. The model call that judges a case is inference
and is on the inference line, not the evaluation line.

A line also names the price version the work was charged under. Prices are
versioned and never edited, and a charge keeps the version in force when the
work was admitted, so a period that spans a price change has a line on each
side of it rather than one total covering both. Work charged before any price
was recorded has no version, and the field is null. What a paid tool's
publisher charged has none either: it is the publisher's quoted price rather than
ours, on a tool line of its own beside the line for the units of the same actions.

Totals are given per usage class and per unit, and never across them.
Simulation credits are not Test Compute and Test Compute is not Live, so there
is no single figure that adds them together. A tool that needs one number
should pick the usage class it means.

A line's `asset` and `scale` say what its amounts count. Work paid with credits
is in credit units at scale nine: shift the digits nine places to read it in
credits. A fraction of a credit that was charged is a fraction that is shown,
and nothing is rounded on the way to you. Work on a budget [paid from a
wallet](https://docs.katara.com/products/wallet-budgets.txt) is in USDC base units at scale six, on lines
and totals of its own, because credits and the USDC a wallet paid are not the
same money. Each wallet charge is rounded down to a whole base unit when it is
made, so the statement shows exactly what the wallet owes for that work.

What a wallet was charged is collected in batches, and each collection is a
transaction. A run's charges list the collections that paid them with their
transaction hashes; see [read what a run paid](https://docs.katara.com/products/wallet-budgets.txt#read-what-a-run-paid).
Wallet payments for chat and API use are a separate record with its own history.

## Checking a statement later

A statement carries an `integrity` digest taken over its own figures. The
TypeScript and Python SDKs expose `verifyStatement` and `verify_statement`,
which recompute the digest from the statement alone. A statement you saved a
year ago can be checked without asking us anything, and a statement whose
figures were edited fails the check.

```ts
import { verifyStatement } from "@katara/platform/products";

const statement = await client.statement(orgId, "2026-08-01T00:00:00Z", "2026-09-01T00:00:00Z");
const checked = await verifyStatement(statement);
for (const total of checked.totals) console.log(total.usage_class, total.charged);
```

## Which period a charge belongs to

A statement answers for the exact window you ask about. A billing period is the
window your plan actually ran in, and `listSubscriptionCycles` /
`list_subscription_cycles` returns them newest first, the period you are in
included.

A period carries the plan revision that priced it, the allowance the plan
included, and the window itself. Once it closes it also carries the digest of the
statement it closed on, so the bill for a period cannot change after it was
settled. A correction is a later entry that refers to the period, never an edit
to it.

```ts
const cycles = await client.listSubscriptionCycles(orgId);
const current = cycles.data.find(cycle => cycle.state === "open");
if (current) console.log(current.period_start, current.period_end, current.allowance);
```

Periods do not overlap and only one is open at a time, so a charge falls in
exactly one of them. The list is paged. Carry its `next_cursor` to the next call
rather than an offset, and a period opened while you are reading cannot make you
skip one.

Opening and closing a period is ours to do, and nothing you can call starts or
ends one. An organization that has not had a period opened for it reads an empty
list; statements are unaffected and answer for any window as they always have.

## What was bought from a paid-tool provider

Paid tools are bought from providers your environment has enrolled.
`listPaidProviders` / `list_paid_providers` lists them: each provider's mode,
how many profile versions it has and whether one is in force.

`getPaidProviderReport` / `get_paid_provider_report` lists what the environment
bought from one provider, one entry per paid action: the quote it was bought
under, the run that planned it, how it settled (`held`, `unknown`, `charged` or
`released`) and the amount charged in atomic credits. Use it to check a
provider's invoice line by line. The receipt digest names the signed receipt a
charge rests on, and `conflict` says the provider later sent a receipt that
disagreed with it. An `unknown` entry is waiting for the provider to say what
happened. Arguments, quote bodies and receipts are never returned, and both
reads need the billing permission in that environment.

## Who can read one

Reading a statement needs the billing permission. Billing is its own role:
someone who can change what your agents do is not thereby entitled to what the
organization spent. Give it to the people who answer for the money.

## Being told

Two notices arrive in the same inbox as everything else:

- **Balance needs attention** is sent when the spendable balance crosses below
  the replenishment threshold you chose. Until you choose one, it is sent once
  80% of the credit you last bought or were granted is spent: with only the $5
  signup credit, that is when $1 is left. It is sent on the crossing rather
  than on every request afterwards, and it stays quiet while automatic
  replenishment is armed, because that is a promise the account has already
  made to itself. If a replenishment then fails, a payment notice covers it.
- **Statement available** is sent once a month has ended, to the payers who were
  actually charged in it. A month nobody spent in produces no notice.

Both can be turned off per channel in notification preferences.

The month this notice covers is the calendar month, and it goes to a payer
rather than to an organization. It is not the same thing as a billing period
closing: a plan's period can start on any day, and nothing is sent when one
closes yet.