> For the complete documentation index, see [llms.txt](https://entrytarget.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://entrytarget.gitbook.io/docs/concepts/double-entry-model.md).

# The Double-Entry Model

This page explains the accounting model EntryTarget implements and the entities you will work with everywhere in the API.

## Double-Entry Bookkeeping

Every financial movement is recorded in at least two accounts: value debited somewhere is credited somewhere else, and total debits always equal total credits.

**Example:** a customer sends US$10.00.

| Account                | Debit    | Credit   |
| ---------------------- | -------- | -------- |
| Customer Payment (USD) | US$10.00 |          |
| Bank Asset (USD)       |          | US$10.00 |

Double-entry gives you a self-balancing system, full auditability (every movement is traceable to its counterpart), and built-in error detection (if debits don't equal credits, something is wrong).

## The Entity Model

```
Transaction (executed atomically)
    |
    |-- Entry 1 (asset: BRL)
    |       |-- Posting 1 (debit 1000 on Account A)
    |       |-- Posting 2 (credit 1000 on Account B)
    |
    |-- Entry 2 (asset: USD)
    |       |-- Posting 1 (debit 200 on Account C)
    |       |-- Posting 2 (credit 150 on Account D)
    |       |-- Posting 3 (credit 50 on Account E)
```

### Account

A financial account holding two running totals — `debit_amount` and `credit_amount` — in a single asset (currency). Each account references a `DETAIL` record of the chart of accounts, which supplies its accounting `type`, `category` and `code_number`; it carries two [balance limits](/docs/concepts/balance-limits.md) of its own (inherited from the chart record at creation) and a `version` that increments on every posting applied. See [Accounts](/docs/concepts/accounts.md).

### Transaction

A group of journal entries executed atomically — either all entries succeed or none do. Identified by a `transaction_id` (UUID). A transaction can contain entries in different currencies.

Every transaction carries a `transaction_model` (`SINGLE` or `PAIRED`) and a `transaction_role` (`STANDALONE` for single transactions; `AUTHORIZATION`, `CAPTURE`, or `VOID` for [paired ones](/docs/concepts/authorizations.md)).

### Entry (Journal Entry)

A bookkeeping entry carrying a list of postings. Each entry declares a `type` label and an `asset`, and **within an entry the sum of debits must equal the sum of credits**. Entries have no id of their own — an entry is identified by its `sequence` within the transaction, assigned by the system from the order you sent the entries.

### Posting

One line within an entry, naming one account, a `debit_amount`, a `credit_amount`, and a `description`. A posting may load one side or both. The posting is the account statement line — the complete, ordered history of an account is its list of postings. See [Transactions, Entries & Postings](/docs/concepts/transactions.md).

## Debits and Credits

Each account keeps **two separate running totals**: `debit_amount` and `credit_amount`. Every posting **adds** to one side (or both) — the totals only grow and are never negative. There is no single signed `balance` column.

The account's *effective balance* is the difference between the two sides. Which side is expected to exceed the other is governed by the account's [balance limits](/docs/concepts/balance-limits.md):

| Setup          | Effective balance              | Typical account           |
| -------------- | ------------------------------ | ------------------------- |
| Credit balance | `credit_amount - debit_amount` | Customer payment accounts |
| Debit balance  | `debit_amount - credit_amount` | Asset / mirror accounts   |
| Unrestricted   | either orientation             | Fee and revenue accounts  |

This mirrors classic accounting: a liability account normally carries a credit balance, an asset account normally carries a debit balance.

## Account Types

Every account is classified under a record of the [chart of accounts](/docs/concepts/accounts.md#the-chart-of-accounts), and that record carries an accounting `type` from a closed set:

`ASSET` · `LIABILITY` · `EQUITY` · `REVENUE` · `EXPENSE`

The type is a classification for reporting and aggregation (the per-asset report renders balances in the shape of the chart of accounts). It does not by itself restrict balances — that is the job of the balance limits. Because the account references the chart record, correcting the record's `type` is reflected on every account under it at once.

## Account Categories

Categories are labels on chart records (up to 100 characters; only `A-Z`, `0-9`, `_`) that describe the purpose of the accounts classified under them (e.g., `PAYMENT_ACCOUNT`, `BANK_ASSET`, `FEE_REVENUE`). They are normalized to uppercase automatically and complement the closed set of accounting types. Within the chart, the pair `(type, category)` is unique.

## Integer Amounts

All monetary values in EntryTarget are **integers**. You control the number of decimal places on your side.

| Real Amount    | Stored Value | Your Decimal Places |
| -------------- | ------------ | ------------------- |
| US$1.00        | `100`        | 2                   |
| R$1.00         | `100`        | 2                   |
| BTC 0.00000001 | `1`          | 8                   |

## Assets (Currencies)

An asset represents a currency or unit of value (e.g., `USD`, `EUR`, `BRL`, `BTC`), up to 5 characters. Every account has a single asset, and every entry declares its asset.

**Rule:** every account referenced by an entry's postings must have the same asset as the entry's declared asset (`422 ASSET_MISMATCH` otherwise). A single transaction can contain entries in different currencies — for example, one entry moving EUR and another moving USD — as long as each entry's accounts match its declared asset.

## Accounting Date

Every transaction carries an `accounting_date` — the business date the movement belongs to. By default it is the UTC date the transaction was created, but you may set it explicitly, including retroactively. It is **informational**: it appears on the transaction detail and on every statement line for your reporting, but the statement's day and ordering come from when each posting was **created** — a retroactive date does not move a line to another day. It is immutable once the transaction is recorded: a wrong date is corrected with a reversing transaction and a new one.

## Identifiers and Timestamps

All entity ids are UUIDs generated by the system — version 7, time-ordered, so ids sort in creation order. All timestamps are ISO 8601 with millisecond precision (e.g. `2026-04-27T14:14:34.479Z`); `accounting_date` fields are plain dates (`YYYY-MM-DD`).

## Consistency Guarantees

EntryTarget guarantees, permanently and verifiably (see [Consistency Checks](/docs/operations/consistency-checks.md)):

1. **Debits = credits, always** — across all accounts and all postings, per asset
2. **Sequential versioning** — each account's version increments by 1 with no gaps
3. **Atomic transactions** — all entries in a transaction succeed or none do
4. **Balance evolution** — every posting records the account's exact post-totals, and they evolve correctly posting by posting
5. **Append-only history** — postings are never mutated; the balance limits in effect at posting time are preserved on each posting

For when each read reflects a write, see [Read Consistency](/docs/concepts/consistency.md).