# Accounting Primer

Double-entry accounting for developers who have never touched a ledger before.

URL: https://docs.shiwake.app/docs/getting-started/accounting-primer





















If you've never worked on a financial system, the vocabulary is the hard
part. "Debit" and "credit" don't mean what they mean at an ATM. "Liability"
sounds bad but describes a customer's wallet balance. This page fixes that
before you touch any code.

You do not need an accounting degree to use Shiwake. You need about
fifteen minutes and the five or six ideas below.

The payoff for learning this: &#x2A;*you can never quietly lose track of
money.** Every movement is recorded twice, and the two halves are forced
to agree. When they don't, the system refuses the write instead of
silently drifting. That guarantee is the whole reason double-entry has
outlived every accounting fad for 500 years.

The mental model [#the-mental-model]

A ledger is a list of facts about money that has already moved. It is not
a bank account, not a balance, not a wallet. It is a log. Balances are
**computed from the log**, not stored as the source of truth.

Every fact in the log must explain *both sides* of a money movement:
where it came from and where it went. That's the whole idea behind
double-entry. You cannot record "money appeared" without also recording
"money disappeared from somewhere else."

If money always moves *from* somewhere *to* somewhere, the total amount
"from" and the total amount "to" must be equal. That is the only rule of
double-entry. Everything else is terminology for that rule.

{/*
  IMAGE PROMPT (mental model: "the ledger is a log"):
  "A clean, minimal isometric technical illustration of a financial ledger as
  an append-only log. Show a vertical stack of horizontal cards (each card = one
  journal entry) flowing downward like a timeline, each card split into a left
  'debit' column and a right 'credit' column of equal height to visually imply
  balance. To the right, a small 'balance' gauge is drawn with a dotted arrow
  pointing FROM the stack TO the gauge, labeled 'computed'. Flat design, thin
  line work, soft neutral background (#f8f9fb), a single accent color (indigo),
  generous whitespace, no text labels except 'LEDGER', 'debit', 'credit',
  'computed'. Developer-documentation aesthetic, 16:9."
  */}

<img alt="The ledger is an append-only log; balances are computed from it" src="__img0" />

The core terms [#the-core-terms]

Account [#account]

An **account** is just a &#x2A;*label you stick on money so you can ask "how
much is here?"** and get one number back. Nothing more.

The trick is: you make a &#x2A;*separate account for every question you want
to answer separately.**

* "How much cash does the company hold right now?" → make an account for
  that. Call it `PLATFORM-FLOAT`.
* "How much do we owe **Alice**?" → make an account for that:
  `CLIENT-42`.
* "How much do we owe **Bob**?" → that's a *different* question, so it's
  a *different* account: `CLIENT-99`.
* "How much have we earned in fees this whole time?" → another account:
  `FEE-REVENUE`.

That's why a real product has thousands of accounts: one for the
company's cash, **one per customer wallet**, one for fees, one for taxes
owed, and so on. Each one just answers its own "how much?" question.

The word "account" is unfortunate: forget your bank account. A better
mental image is a **labeled jar**. Money movements drop coins into jars
or take them out, and the account is simply the running count in one jar.
You never store that count; you get it by counting the jar (summing the
log) whenever someone asks.

{/*
  IMAGE PROMPT (what an account is: labeled jars):
  "A clean, minimal flat-design illustration explaining the concept of an
  accounting 'account' as a set of labeled jars. Show four transparent jars in a
  row, each with a printed label tag and a small coin-stack inside at a different
  fill level. Label the jars: PLATFORM-FLOAT ('company cash'), CLIENT-42
  ('Alice's wallet'), CLIENT-99 ('Bob's wallet'), and FEE-REVENUE ('fees
  earned'). Above each jar, a small question in a speech bubble it answers: e.g. 'How much cash do we hold?', 'How much do we owe Alice?', 'How much do we
  owe Bob?', 'How much have we earned in fees?'. Below each jar, a number readout
  labeled 'balance' with a small '= count the jar' caption to imply the balance
  is computed, not stored. Thin line work, indigo accent color, soft neutral
  background (#f8f9fb), clean sans-serif labels, generous whitespace, developer-
  documentation aesthetic, 16:9."
  */}

<img alt="An account is a labeled jar: one per question you want to answer, and its balance is just the running count" src="__img1" />

In Shiwake, every account has just four things:

* a **code**: the unique handle you refer to it by, like `CLIENT-42`
* a **name**: a human label, like "Alice's wallet"
* a **type**: one of the five kinds below (Asset, Liability, …), which
  decides whether debits grow it or shrink it
* a **currency**: an account only ever holds one currency

Journal entry [#journal-entry]

A **journal entry** is &#x2A;*one complete story of a single money movement.**
"Alice deposited 500" is one journal entry. "We paid out a refund of 200"
is another. Each entry is one row in the log, and it never gets edited or
deleted once written.

But a story needs at least two characters, where the money came *from*
and where it went *to*. So an entry isn't just one number; it's a small
container holding:

* a **description** ("Alice deposit") and a **timestamp**, and
* **two or more lines**: the actual pieces that say which jars moved.

Think of the entry as an **envelope** and the lines as the &#x2A;*slips of
paper inside it.** The envelope is the event; the slips are the details.
You always post the whole envelope at once, never a lone slip.

Entry line [#entry-line]

A **line** is one slip inside the envelope. It says exactly three things:

1. **which account** moved (`CLIENT-42`),
2. **how much** (50000), and
3. **which side**: a *debit* or a *credit*.

That's it. One line touches exactly one account. A minimum entry has
**two** lines (one debit, one credit: the "from" and the "to"). Bigger
entries can have more: splitting a payment into principal + fee + tax
might have four or five lines. The only unbreakable rule is that, added
up, &#x2A;*the debit lines and the credit lines must total the same amount.**
That's what "the envelope balances" means.

{/*
  IMAGE PROMPT (journal entry = envelope, lines = slips inside):
  "A clean, minimal flat-design illustration of a journal entry as an open
  envelope containing slips of paper. The envelope has a header printed on its
  flap: 'Alice deposit: 2026-07-01' (description + timestamp). Inside/emerging
  from the envelope are two slips of paper, each a 'line': slip 1 reads
  'PLATFORM-FLOAT | 50000 | DEBIT', slip 2 reads 'CLIENT-42 | 50000 | CREDIT'.
  Each slip clearly shows its three parts labeled subtly: account, amount, side.
  At the bottom of the envelope, a small balance scale sitting perfectly level
  with '50000' on each pan and a caption 'debits = credits'. Convey that the
  envelope is posted as a whole. Thin line work, indigo accent color, soft
  neutral background (#f8f9fb), clean sans-serif labels, generous whitespace,
  developer-documentation aesthetic, 16:9."
  */}

<img alt="A journal entry is an envelope; its lines are the slips inside, each naming one account, one amount, and one side" src="__img2" />

Debit and credit [#debit-and-credit]

Here is the sentence to tattoo on your brain:

> **Debit and credit are just "left side" and "right side" of the ledger.
> They are not "money in" and "money out."**

Whether a debit means "the account grew" or "the account shrank" depends
on the type of account. That's what "normal balance" means below.

Forget everything your bank statement taught you. In a bank statement, a
"debit" takes money from you, because the statement is written from
*your* perspective, but to the bank, that same transaction is a credit
(their liability to you went down). Double-entry keeps one side in one
column and the other side in the other, consistently, across the entire
ledger.

{/*
  IMAGE PROMPT (debit = left, credit = right):
  "A minimal flat-design diagram of a T-account, the classic accounting 'T'
  shape. A horizontal line over a vertical line forming a large T. The left
  region is labeled 'DEBIT' and the right region is labeled 'CREDIT', each with
  a small directional icon (left arrow on the debit side, right arrow on the
  credit side). Above the T, crossed-out bank-statement wording 'money out /
  money in' shown faded and struck through to signal 'this is NOT what they
  mean'. Thin line work, indigo accent, neutral #f8f9fb background, lots of
  whitespace, documentation illustration style, 16:9."
  */}

<img alt="Debit is the left side and credit is the right side of the ledger, not money out and money in" src="__img3" />

Account types and normal balances [#account-types-and-normal-balances]

There are five kinds of accounts. Each one has a side it "grows on"
(called its **normal balance**):

| Type          | Grows on | Shrinks on | Example                             |
| ------------- | -------- | ---------- | ----------------------------------- |
| **Asset**     | Debit    | Credit     | The cash the company holds          |
| **Liability** | Credit   | Debit      | Money the company owes customers    |
| **Equity**    | Credit   | Debit      | The owners' stake                   |
| **Revenue**   | Credit   | Debit      | Fees and interest the company earns |
| **Expense**   | Debit    | Credit     | Costs the company incurs            |

One way to remember it: &#x2A;*assets and expenses grow on the debit side;
everything else grows on the credit side.**

<Callout type="info">
  **Cheat sheet: screenshot this.**

  * **DE**bit-normal (grow on debit): **A**ssets, **E**xpenses
  * **C**redit-normal (grow on credit): **L**iabilities, **E**quity,
    **R**evenue
  * Same-side entry → the account **grows**. Opposite side → it
    **shrinks**.
  * Every entry: &#x2A;*total debits = total credits.** No exceptions.
</Callout>

{/*
  IMAGE PROMPT (five account types + normal balances):
  "A minimal flat infographic showing the five accounting account types as five
  labeled tiles arranged in a row or grid: Asset, Liability, Equity, Revenue,
  Expense. Each tile shows a small icon and a 'grows on' indicator: an upward
  arrow tagged 'DEBIT' for Asset and Expense, and an upward arrow tagged
  'CREDIT' for Liability, Equity, and Revenue. Use two subtle background tints to
  group them: the two debit-normal tiles in one tint, the three credit-normal
  tiles in another. Thin line icons (cash stack for Asset, wallet/IOU for
  Liability, pie slice for Equity, coin-plus for Revenue, receipt for Expense),
  indigo accent, neutral #f8f9fb background, clean sans-serif labels,
  documentation style, 16:9."
  */}

<img alt="The five account types and the side each one grows on" src="__img4" />

Another way: debits and credits are just labels. What matters is that
the rule "debits = credits" holds for every entry.

Working an example, very slowly [#working-an-example-very-slowly]

We'll follow **one customer, Alice**, through three events in a row (a deposit, a withdrawal, and a fee) and watch her wallet balance move
after each one. That running balance is the whole point of the page:
nobody stores it, it just *falls out* of summing the entries.

**Event 1: Alice deposits GHS 500 into her wallet.** There are two
accounts involved:

* `PLATFORM-FLOAT`: the company's cash pile. This is an **Asset**.
* `CLIENT-42`: the customer's wallet. This is a **Liability** (the
  company owes them 500 now).

<Callout type="warn">
  **Why is a customer's wallet a "liability"?** Because the ledger is
  written from the *company's* perspective, not the customer's. Money
  sitting in Alice's wallet is money the company owes back to Alice. A
  debt it must be able to pay out on demand. Her asset is the company's
  liability. Get this one reframe and the entire normal-balance table
  suddenly makes sense.
</Callout>

Here is the journal entry:

| Account          | Type      |     Debit |    Credit |
| ---------------- | --------- | --------: | --------: |
| `PLATFORM-FLOAT` | Asset     |     50000 |           |
| `CLIENT-42`      | Liability |           |     50000 |
|                  |           | **50000** | **50000** |

Let's read it out loud:

* **`PLATFORM-FLOAT` is debited 50000.** It's an asset, and assets grow on
  debits. So the company's cash pile grew by 500.
* **`CLIENT-42` is credited 50000.** It's a liability, and liabilities
  grow on credits. So what the company owes the customer grew by 500.
* **Debits equal credits** (50000 = 50000). The entry balances. It can be
  posted.

Both sides make sense. Cash came in; a debt to the customer came into
existence. The books are still in balance because both sides grew by the
same amount.

**Alice's wallet balance after Event 1: 50000** (one credit of 50000, no
debits yet).

{/*
  IMAGE PROMPT (deposit flow: worked example):
  "A minimal flat-design flow diagram of a customer deposit. On the left, a
  person icon labeled 'Customer' with '+GHS 500' flowing via an arrow into a box
  labeled 'PLATFORM-FLOAT (Asset)' marked 'DEBIT 50000 ▲'. A second box labeled
  'CLIENT-42 (Liability)' marked 'CREDIT 50000 ▲'. Below the two boxes, a balance
  scale perfectly level, with '50000' on each pan, captioned 'debits = credits'.
  Amounts shown in minor units. Thin line work, indigo accent, neutral #f8f9fb
  background, generous whitespace, documentation illustration style, 16:9."
  */}

<img alt="Deposit: PLATFORM-FLOAT debited and CLIENT-42 credited, both by 50000" src="__img5" />

<Callout type="info">
  The number `50000` here is not "fifty thousand cedis." It's GHS 500.00
  in **pesewas**: minor units. Everything in Shiwake is minor units,
  always. GHS 1.00 is `100`, USD 1.00 is `100`, JPY 1 is `1`.
</Callout>

Event 2: Alice withdraws [#event-2-alice-withdraws]

**Event 2: Alice withdraws GHS 200.** Same two accounts as before, but
now both sides shrink:

| Account          | Type      |     Debit |    Credit |
| ---------------- | --------- | --------: | --------: |
| `CLIENT-42`      | Liability |     20000 |           |
| `PLATFORM-FLOAT` | Asset     |           |     20000 |
|                  |           | **20000** | **20000** |

* **`CLIENT-42` is debited 20000.** Liabilities shrink on debits. The
  company owes the customer 200 less now.
* **`PLATFORM-FLOAT` is credited 20000.** Assets shrink on credits. The
  company's cash pile is 200 smaller.

**Alice's wallet balance after Event 2: 30000** (credits 50000 − debits
20000\). Nobody wrote "30000" anywhere. It's just the credits minus the
debits so far.

Notice how the debit/credit labels *flipped sides* compared to the
deposit. That's the whole point. The same pair of accounts can move in
either direction depending on which side you put them on.

{/*
  IMAGE PROMPT (deposit vs withdrawal: the sides flip):
  "A minimal side-by-side comparison illustration. Two panels labeled 'DEPOSIT'
  and 'WITHDRAWAL'. Each panel shows the same two accounts, PLATFORM-FLOAT and
  CLIENT-42, in a two-column debit/credit table. In the DEPOSIT panel the debit
  mark sits on PLATFORM-FLOAT and the credit on CLIENT-42; in the WITHDRAWAL
  panel the marks are swapped to the opposite accounts. A curved 'flip' arrow
  between the two panels emphasizes the mirroring. Thin line work, indigo accent,
  neutral #f8f9fb background, clean labels, documentation style, 16:9."
  */}

<img alt="The same two accounts, with debit and credit flipped between deposit and withdrawal" src="__img6" />

Event 3: Alice pays a fee [#event-3-alice-pays-a-fee]

**Event 3: Alice pays a GHS 5 fee out of her wallet.** A new account
appears. The fee doesn't go back to the float, it becomes the company's
revenue:

| Account       | Type      |   Debit |  Credit |
| ------------- | --------- | ------: | ------: |
| `CLIENT-42`   | Liability |     500 |         |
| `FEE-REVENUE` | Revenue   |         |     500 |
|               |           | **500** | **500** |

* `CLIENT-42` is debited: the customer's wallet shrinks.
* `FEE-REVENUE` is credited: the company's revenue grows.

Still balanced. This is a single journal entry with two lines, just like
the others. The only thing that changed is which accounts are involved.

**Alice's wallet balance after Event 3: 29500** (credits 50000 − debits
20500\).

Here's the whole story in one view: three entries, one running balance,
never stored anywhere:

| After event         | Entry        | `CLIENT-42` running balance |
| ------------------- | ------------ | --------------------------: |
| Start               |              |                           0 |
| 1. Deposit GHS 500  | credit 50000 |                   **50000** |
| 2. Withdraw GHS 200 | debit 20000  |                   **30000** |
| 3. Fee GHS 5        | debit 500    |                   **29500** |

Sum the credits (50000), subtract the debits (20000 + 500), and you get
29500 every time, no matter what order you replay the log in.

Why "debits = credits" is load-bearing [#why-debits--credits-is-load-bearing]

Because every fact in the log balances, the **sum of all debits across
the whole ledger always equals the sum of all credits**. If those two
numbers ever disagree, something is broken at a very deep level. The
[trial balance](/docs/api/reconciliation) endpoint computes exactly those
two numbers and tells you whether they match.

This is also why Shiwake rejects unbalanced entries at post time. The
engine literally cannot let you write a broken fact into the log, because
one broken fact would permanently poison the ledger.

{/*
  IMAGE PROMPT (trial balance / post-time guard):
  "A minimal flat illustration of a balance guard. Center: a large balance scale.
  Left pan labeled 'Σ debits', right pan labeled 'Σ credits'. Two scenarios shown
  subtly: a green 'accepted' checkmark when the scale is level, and a faded red
  'rejected' state where the scale tips and a shield/blocker icon stops an
  unbalanced entry from entering the log on the right. Thin line work, indigo
  primary accent with a small green and red for the two states, neutral #f8f9fb
  background, documentation illustration style, 16:9."
  */}

<img alt="Trial balance: the engine rejects any entry where total debits do not equal total credits" src="__img7" />

Running balances are derived [#running-balances-are-derived]

Notice that nothing in Alice's three events said "store the wallet
balance somewhere." The balance is whatever falls out of summing the log.
`CLIENT-42` has a balance of 29500 because its credits sum to 50000 and
its debits sum to 20500. If you ever doubt the balance, you can recompute
it from scratch from the entry lines. That's what
[verify-balances](/docs/api/reconciliation#verify-balances) does.

Shiwake does cache balances for performance (reading a wallet shouldn't
have to sum millions of rows), but the cache is subordinate to the log.
The log is the truth.

Reversing, not deleting [#reversing-not-deleting]

Suppose the deposit was wrong: the customer actually sent GHS 500 to the
wrong account and you need to undo it. You do **not** delete the journal
entry. You post a **reversal**. A new entry with the debits and credits
swapped, pointing back at the original:

| Account          | Debit | Credit |
| ---------------- | ----: | -----: |
| `CLIENT-42`      | 50000 |        |
| `PLATFORM-FLOAT` |       |  50000 |

The original entry still exists. The reversal also exists. Both are in
the log forever. The net effect on balances is zero, but the history of
what actually happened. "we posted a deposit, then we undid it": is
preserved. An audit trail that can be edited is not an audit trail.

{/*
  IMAGE PROMPT (reversal, not deletion):
  "A minimal flat illustration contrasting 'reverse' with 'delete'. Show a
  timeline log of entry cards. One original entry card is highlighted, and a new
  card labeled 'REVERSAL' is appended after it with debits and credits mirrored
  (swapped columns) and a dotted arrow pointing back to the original card. A
  trash-can icon appears crossed out / disabled to show deletion is not allowed.
  A small 'net effect = 0' badge sits beside the pair while both cards remain
  visible in the log. Thin line work, indigo accent, neutral #f8f9fb background,
  documentation illustration style, 16:9."
  */}

<img alt="A reversal appends a mirrored entry pointing back at the original; nothing is ever deleted" src="__img8" />

One more idea: holds [#one-more-idea-holds]

Sometimes you need to *reserve* money without moving it yet, like an
authorization on a card before the final charge lands. That's a **hold**:
it lowers the *available* balance so the money can't be spent twice, but
it posts no journal entry and doesn't touch the actual balance. When the
real transaction settles, you release the hold and post a normal entry.

The takeaway for now: a hold is a promise, not a movement. Only journal
entries move money. Holds get their own page later. This is just so the
word isn't a surprise in the glossary below.

Glossary [#glossary]

| Term               | Meaning                                                               |
| ------------------ | --------------------------------------------------------------------- |
| **Ledger**         | The log of all journal entries. The source of truth                   |
| **Account**        | A named bucket whose balance is computed from the log                 |
| **Journal entry**  | A single atomic fact in the log, with ≥2 lines                        |
| **Line**           | One side of one entry: an account, an amount, and a debit/credit flag |
| **Debit / credit** | Left side / right side of the ledger. Not "in" and "out"              |
| **Normal balance** | The side (debit or credit) an account type grows on                   |
| **Asset**          | Something the company owns (cash, receivables). Grows on debit        |
| **Liability**      | Something the company owes (wallets, deposits). Grows on credit       |
| **Equity**         | Ownership stake. Grows on credit                                      |
| **Revenue**        | Income earned (fees, interest). Grows on credit                       |
| **Expense**        | Costs incurred. Grows on debit                                        |
| **Trial balance**  | Sum of all debits vs sum of all credits. Must be equal                |
| **Reversal**       | A new entry that cancels an earlier one. Never a delete               |
| **Hold**           | A reservation against available balance without moving money          |
| **Minor units**    | The smallest unit of a currency. 1 cedi = 100 pesewas                 |

Where to go next [#where-to-go-next]

<Cards>
  <Card title="Core concepts" href="/docs/getting-started/concepts">
    Now that you know the accounting, learn how Shiwake specifically
    models tenants, accounts, and holds.
  </Card>

  <Card title="Quickstart" href="/docs/getting-started/quickstart">
    Post your first journal entry against a real tenant.
  </Card>
</Cards>
