> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Accounting Entries
> Map transaction actions and route directions to accounting classifications, and annotate every operation with its accounting code and description.
Accounting Entries (also known as **Rubricas**) map a transaction action and route direction to an accounting `code` and `description`. They annotate an operation after route resolution; Operation Route rules and transaction legs determine the participating accounts.
## What are Accounting Entries
***
A **rubric** maps a transaction action and route direction to an accounting classification. Instead of computing each classification by hand, you register rubrics once. Midaz then resolves them automatically as it processes transactions.
Each rubric carries:
* **`code`** — an accounting code (for example, `1.1.1.001`).
* **`description`** — a human-readable label for the entry (e.g., `Customer checking — outbound`).
* A set of **action mappings** — one entry per action type, each with its own debit and/or credit rubric.
When the engine processes a transaction with route validation (`accounting.validateRoutes`) enabled and a matching rubric registered, it resolves the rubric for each operation. It records the resulting **`routeCode`** and **`routeDescription`** on the operation. This gives you a complete audit trail from transaction to operation to rubric. Your teams can trace exactly which accounting rule applied to each movement.
Configure rubrics per action on each Operation Route. For `direct` and `commit` actions, **Source** routes require the **debit** rubric and **Destination** routes require the **credit** rubric. Dedicated `block` and `unblock` rubrics are optional; when absent, Midaz resolves the `direct` rubric for those actions. Source-side `hold` and `cancel` actions require **both** rubrics, and `overdraft` requires **both** on every supported route type. **Bidirectional** routes always require **both**.
## The 8 action types
***
Each action represents a distinct transactional event. The first five actions cover the transaction lifecycle. The last three cover overdraft, block, and unblock movements. A single rubric can map different debit and credit classifications for each action. Every stage of an operation then receives the right accounting annotation.
| Action | Identifier | Description |
| :------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Direct** | `direct` | Immediate, single-step debit/credit between two accounts, with no intermediate stages (e.g., a fee or adjustment). |
| **Hold** | `hold` | Reserves funds by creating a pending movement (moves value from `available` to `on_hold` on the source account). |
| **Commit** | `commit` | Confirms a previously held amount, releasing the `on_hold` value to the destination account. |
| **Cancel** | `cancel` | Cancels/reverses a hold, returning the `on_hold` value to the `available` balance on the source account. |
| **Revert** | `revert` | Reverses a completed `direct` transaction by creating a counter-transaction that undoes the original. |
| **Overdraft** | `overdraft` | Classifies overdraft movements — the **debit** rubric marks overdraft usage (the deficit grows) and the **credit** rubric marks repayment (the deficit shrinks). Both rubrics are required when this entry is configured. |
| **Block** | `block` | Optionally classifies a fund-block movement that freezes value on an account (for example, an `asset-freeze`). |
| **Unblock** | `unblock` | Optionally classifies the release of previously blocked funds back to the `available` balance. |
**Overdraft** classifies companion operations that the engine generates automatically during overdraft usage and repayment. For every supported route type and direction, configure both the debit and credit rubrics. **Block** and **unblock** can use dedicated rubrics for operations that the block and unblock transaction endpoints produce; without them, those actions use the `direct` rubric. When needed, register dedicated rubrics for these actions in the same way as for the other actions.
Each action can point to different debit and credit accounting classifications within the same rubric. Map only the actions a route uses. If you enable strict validation (below), cover every action your transactions emit.
## Configuring Accounting Entries
***
You register rubrics through the API as part of your Operation Routes. The `accountingEntries` block on a route defines one entry per action. Each entry carries its `debit` and/or `credit` rubric:
```json accountingEntries theme={null}
{
"accountingEntries": {
"direct": {
"debit": {
"code": "1.1.1.001",
"description": "Customer checking — outbound"
},
"credit": {
"code": "1.1.1.002",
"description": "Customer checking — inbound"
}
},
"hold": {
"debit": {
"code": "1.1.1.001",
"description": "Customer checking — reserve"
},
"credit": {
"code": "2.1.1.001",
"description": "Pending settlement — hold"
}
}
}
}
```
You manage these entries through the Operation Route endpoints — see [Create an Operation Route](/en/reference/midaz/create-an-operation-route) and [Update an Operation Route](/en/reference/midaz/update-an-operation-route). For the full configuration flow, refer to [Transaction Routing](/en/midaz/transaction-routing-entities#4-configure-accounting-entries-actions).
## Validation modes
***
Midaz reacts to a missing rubric based on the Ledger's accounting settings. Two distinct gates control this behavior:
### Default (graceful)
By default (`accounting.validateRoutes` disabled), Midaz does not resolve rubrics at all: the transaction proceeds normally and the `routeCode` and `routeDescription` fields stay empty (nil) for every operation. It raises no error.
### Strict (opt-in)
Set `accounting.validateRoutes` to `true` in the [Ledger Settings](/en/midaz/ledgers#ledger-settings) to enforce route validation. In strict mode, a requested action with no routes in the transaction-route cache returns `0157 ErrNoRoutesForAction`. `0117 ErrAccountingRouteNotFound` applies when an operation route ID is absent from that cache.
```json PATCH /v1/organizations/{org_id}/ledgers/{ledger_id}/settings theme={null}
{
"accounting": {
"validateRoutes": true
}
}
```
In strict mode, do not treat `0117 ErrAccountingRouteNotFound` as the error for every unmapped action: it applies when an operation route ID is absent from the transaction-route cache. A requested action with no routes in that cache returns `0157 ErrNoRoutesForAction`.
Use **strict mode** in production ledgers where every transaction type needs an accounting classification. The graceful default helps while you onboard routes. In production, it can silently leave movements without a classification.
When Midaz finds a matching rubric, it annotates the operation with two fields:
* **routeCode** — the `code` of the resolved `AccountingRubric` for that action and direction.
* **routeDescription** — the description of the resolved rubric, populated alongside `routeCode`.