Core Concepts
Double-entry accounting, tenants, accounts, journal entries, and holds.
This page covers the Shiwake-specific model: tenants, accounts, entries, balances, and holds as they exist in the engine. If the words "debit" and "credit" don't feel natural yet, read the Accounting Primer first: everything below assumes you know what a balanced journal entry is.
Journal entries are immutable
Once a journal entry is posted, it never changes. If you need to undo it,
you post a reversal: a new journal entry with the debits and credits
swapped, pointing back at the original via reversalOf. Both entries live
forever in the ledger. This is not a limitation; it is the point. A ledger
that can be retroactively edited is not an audit trail.
Tenants and isolation
A tenant is a complete, isolated set of books. Every account, journal entry, and hold belongs to exactly one tenant, and tenant-scoped requests can never see another tenant's data. The filter is enforced at the database layer by EF Core global query filters, not by application code.
In practice this means:
- One Shiwake deployment can serve many independent products.
- One tenant's rate limit exhaustion cannot affect another.
- Account codes only need to be unique within a tenant. Two tenants can
both have a
CLIENT-42. - API keys map one-to-one to tenants. See Authentication.
Accounts
An account is a named bucket that holds a balance in a single currency. Every account has:
- A code: stable, human-readable, unique per tenant (e.g.
CLIENT-42,PLATFORM-FLOAT). This is what you reference from journal entry lines. - An id: ULID, what the API returns for cross-references.
- A type: Asset, Liability, Equity, Revenue, or Expense.
- A currency: ISO 4217 code. Fixed at creation.
- A parent: optional, for hierarchical reporting.
See Accounts for the full field reference.
Two balances, not one
Every account actually has two balances:
- Ledger balance: the sum of posted debits and credits. This is the "real" accounting balance.
- Available balance:
ledger balance − active holds. This is what the engine checks when you try to debit the account.
If a wallet has GHS 500 and you've placed a GHS 200 hold on it, the
ledger balance is still 500 but the available balance is 300. A new debit
of 400 will be rejected with 422 Insufficient balance even though the
ledger "has the money". The 200 is reserved.
Holds
A hold reserves an amount on an account's available balance without moving money. It's the right primitive for authorization flows where you need to guarantee funds now but settle later (or settle at a different amount).
Holds have a lifecycle: Active → Captured (settled by posting a
journal entry) or Released (abandoned) or Expired (timed out).
See Holds for the full API.
What happens when you post an entry
When POST /ledger/journal-entries is called, the engine:
- Verifies the
Idempotency-Keyheader is present and not a replay. - Loads the referenced accounts, failing with
404on any unknown code. - Checks that debits equal credits per currency.
- Checks that debiting would not drive any account below its available
balance, failing with
422and anInsufficientBalanceDetailpayload. - Inserts the entry, the lines, and updates cached balances: all in one transaction.
Either everything happens or nothing does. There is no half-posted entry.
Where to go next
Last updated on