Last reviewed: 2026-06-16

Journal Entry Contract

Canonical object: JournalEntry

Canonical child object: JournalEntryLine

Required concepts: - header - lines - id - company_id - posting date - financial period - source reference - explanation - balanced debits and credits - creation and posting attribution

JournalEntry required fields: - id - company_id - posting_date - financial_period_id - source_type - source_id - explanation - status - posted_at - posted_by_actor_id

JournalEntryLine required fields: - id - journal_entry_id - account_id - description when applicable - debit amount - credit amount - currency

Rules: - Entries must balance before posting. - Posted entries are corrected through reversal or adjustment. - Each line must reference an account. - Posted entries are append-oriented accounting records and must not be silently mutated. - Routine posting must use one central posting path. - Routine posting requires the posting date to resolve to an eligible financial period. - Routine posting requires active posting accounts unless an authorized historical or correction process allows otherwise. - Manual routine posting does not require an idempotency key in the initial posting foundation. - Source references may initially be stored as an opaque source type and source identifier until the Source Documents implementation is available. - Human-visible journal entry numbering is deferred; entry identity is stable by id in the initial posting foundation.

Allowed statuses: - posted

Validation expectations: - debit and credit totals match. - each line has account and amount. - source and period are present for posted entries. - persisted status values use the stable snake_case contract values defined by this contract. - debit and credit amounts are non-negative and a line must not carry both a debit and credit amount. - a posted entry has at least two lines. - routine posting rejects planned, soft-closed, and hard-closed periods unless a later authorized correction or close-adjustment process explicitly applies.

Related truth pages: - ../accounting/journal-entries.md - ../accounting/posting-and-reversal.md - account.contract.md - financial-period.contract.md - money.contract.md