Core concepts

LedgerLou arranges the general ledger on three levels:

Journal -> Intents -> Posting lines

The journal is the overall view. It contains many intents. Each intent groups one or more posting lines that together form a single posting transaction.

Concept	What it is	Persistence
Journal	Append-only overall view of all intents for a tenant	ledger_events (GoBD-compliant, hash-chained)
Intent	Business bracket for exactly one posting transaction within the journal	No dedicated record — carried as intent_id in ledger_events, documents, bank_transactions and others
Posting line	Single debit/credit line within an intent	ledger_events (1+ lines per intent)

In practice this means:

• The journal lists all intents chronologically.
• An intent groups the lines that belong to a single transaction.
• A posting can consist of one or more posting lines, depending on splits and tax logic.

Intent lifecycle

An intent is immutable. Once its lines are in the journal they are never modified or deleted — not even when downstream modules such as bank reconciliation later unlink their assignment. Corrections arise exclusively through new intents that point back to the origin via reverses_intent_id.

Three typical scenarios show how this plays out in concert with bank reconciliation:

Reversal logic

In LedgerLou a reversal is always a new posting intent. The original lines remain unchanged; the reversal lines mirror debit and credit, carry over audit-relevant fields such as the FX block, external_reference, custom_metadata, and tax_code, and carry reverses_intent_id pointing at the reversed intent.

For the posting date, there are two modes:

Mode	REST posting_mode	MCP posting_mode	Effect
Current period	current_period or omit	current_period or omit	Reversal is posted with today’s date in the current open period. This is the default for API and MCP so that existing integrations remain stable.
Original period	original_period	original_period	Reversal is set to the posting date of the original posting. Useful for year-end or period corrections, as long as the original period is still open.

original_period is an explicit correction mode. Before writing, LedgerLou checks whether the target period is open. If it is soft-locked or hard-locked, the reversal is rejected with PERIOD_LOCKED. In that case the period must be deliberately reopened, or the correction stays in the current period.

For already-reconciled intents, LedgerLou first reverses dependent settlement intents and releases the bank linkage. Grouped bank reconciliations remain protected: if a settlement still clears other active intents, the group assignment must be released first.

curl -X POST https://api.ledgerlou.de/v1/journal/reverse \
  -H "Authorization: Bearer $LEDGERLOU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reason": "Falsche Kontierung",
    "posting_mode": "original_period"
  }'

The same applies for MCP.

{
  "intent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "reason": "Falsche Kontierung",
  "posting_mode": "original_period"
}

Metadata & external references

Every posting can optionally carry two intent-level fields that link the transaction to external systems or provide additional context:

Property	external_reference	custom_metadata
Type	string (max. 500 characters)	Flat JSON object (string | number | boolean | null as values)
Required	No	No
Immutable	Yes (GoBD)	Yes (GoBD)
In audit hash	Yes	Yes (deterministic ordering)
Filterable	GET /v1/journal?externalReference=...	—
Reversal behavior	Copied identically from the original	Copied identically from the original

Typical use cases:

• Invoice number as reference — external_reference: "RE-2025-0042" links the posting to the invoice in the ERP. Via ?externalReference=RE-2025-0042 the corresponding journal entry is immediately findable.
• Cost center and project — custom_metadata: { "cost_center": "CC-100", "project": "alpha" } assigns the posting organizationally without having to adapt the chart of accounts model.
• Origin tags for automations — custom_metadata: { "source_system": "shopify", "order_id": "ORD-9981" } gives MCP agents and ETL pipelines a structured return channel.

Foreign-currency postings

LedgerLou keeps the books in EUR. Postings in a foreign currency (e.g. USD, GBP, CHF) are posted natively as the EUR amount and additionally carry an FX block with the original data:

Field	Meaning
currency	ISO 4217 currency code (e.g. USD)
foreign_amount	Gross amount in foreign currency
rate	Conversion rate foreign currency → EUR (ECB convention)
rate_date	Effective date of the rate
rate_source	Source (e.g. ECB, manual, bank)

Important rules:

• The caller provides the rate explicitly — LedgerLou does not query external rate sources.
• The EUR amount in lines must match the FX block: foreign_amount × rate ≈ sum of debit amounts (tolerance: max. 1 cent or 0.01%).
• For split postings, the foreign-currency amount is allocated proportionally across the lines (largest-remainder method, 4 decimal places).
• Reversal postings carry over the FX block identically from the original — no new rate is calculated.
• EUR postings set no FX block (fx: null or field omitted).
• Opening-balance values (POST /v1/bookings/opening-balances) do not support FX.

Workflow

Access methods

Scopes