> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.
# The Journal
> The append-only log of every financial action
The **journal** is the record of what was done. One row per action, appended in
the order the actions executed, and never touched again.
Everything else in Financials is downstream of it. The ledger rows are stamped
with the journal row that produced them; the [invoice you see on screen](/financials/invoices) is a
summary of its own journal rows. If the journal survives, nothing is lost.
## What a Journal Row Carries
| Field | What it is |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Action type** | Which of the actions below occurred. |
| **Payload** | The action's details — the line items on a creation, the amount and date on a payment, the new balance on a reserve update. Shaped per action type. |
| **Invoice** | The invoice the action was about, on every `invoice.*` action. |
| **Event** | Set on the reserve actions, which are permanently scoped to one event. |
| **Sequence** | A monotonic number fixing the execution order of every action in the company. |
| **Created at** | When the action was executed. Distinct from the *effective date* the ledger posts at. |
| **Created by** | The real acting principal — the signed-in user, or a fixed service identity for machine writers such as the external API. Never supplied by the caller. |
| **Display author** | An optional user-visible author label an integration can set, for actions imported from another system. The acting principal above is recorded regardless. |
## The Actions
Fourteen action types exist, and no other way to change financial state.
| Action | Raised when |
| ------------------- | ----------------------------------------------------------------------------- |
| `invoice.created` | An invoice comes into existence, with its type and line items |
| `invoice.finalized` | A draft becomes a real invoice — the moment its type and line items are fixed |
| `invoice.updated` | An editable field changes: the dates, the memos, the field data |
| `invoice.voided` | The invoice is voided, reversing everything it posted |
| `invoice.restored` | A voided invoice is brought back |
| `invoice.deleted` | The invoice is soft-deleted, sweeping its postings away |
| Action | Raised when |
| -------------------------- | ------------------------------------------------------------------ |
| `invoice.payment_recorded` | Money is recorded as having moved against the invoice's line items |
| `invoice.payment_removed` | A recorded payment is taken back off |
| Action | Raised when |
| ----------------------- | ------------------------------------------------ |
| `invoice.relinked` | The event or policy the invoice is about changes |
| `invoice.payee_changed` | The payee changes |
| `invoice.approved` | The invoice is approved for payment |
| `invoice.unapproved` | That approval is withdrawn |
| Action | Raised when |
| ------------------------ | ----------------------------------------------------------------------- |
| `reserves.set` | A reserve balance is declared for one Invoice Type on one event |
| `reserves.history_reset` | That type's accumulated reserve history on the event is unwound to zero |
Notice what is *not* in the list: there is no action for amending an invoice's
line items, and none for changing its type. Those are not restricted operations —
they are operations that do not exist. This is the mechanism behind the rule in
[Invoices](/financials/invoices): type and line items are fixed at creation.
## An Invoice Is Its Journal, Folded
To know an invoice's current state, the engine reads every journal row for that
invoice in sequence order and **folds** them into a single picture — its line
items, its status, what has been paid, whether it is approved. The fold is the
authority. Every precondition check runs against it, never against the
convenience copy in the read tier.
A payment is recorded against invoice INV-000412-001.
The engine replays the invoice's existing rows to establish what it is right
now — is it voided, is it already fully paid, does the cited line item exist.
A payment on a voided invoice is refused here. The refusal is based on
replayed history, so it cannot be fooled by a stale cache.
Only once the action is admitted does anything get written — the journal row,
its balanced ledger batch, and the updated projection, all in one
transaction.
## Order and Concurrency
Two actions on the same invoice never interleave. Each action takes a lock on the
invoice it touches — and on each [reserve scope](/financials/reserves) it posts into, in a fixed order —
so a payment and a void racing for the same invoice resolve one after the other,
each seeing the other's completed effect.
The sequence number on every row records that resolved order permanently.
## Retries Do Not Double-Post
A caller may supply the id for the journal row it is about to create. If the same
id arrives twice — a network retry, a resubmitted request — the second attempt
resolves to the action already recorded rather than appending a duplicate.
This is why an integration recording payments through the API should generate and
reuse its own action id per payment. A retry without one is a genuinely new
action, and will post a second payment.