Journal Entries
Post, read, list, and reverse balanced double-entry journal entries.
A journal entry is an atomic movement of money between accounts. Every entry contains two or more lines, each debiting or crediting one account, and the lines must balance: for every currency, the sum of debits equals the sum of credits. Shiwake posts the lines, updates account balances, and writes an account transaction row for each line: all inside a single database transaction.
All endpoints on this page live under /api/v1/ledger/journal-entries and
require an X-Api-Key header. Mutating endpoints
additionally require an Idempotency-Key.
The JournalEntry object
{
"id": "je_01HZYX4K2M8Q5R3T9VB6WC0JG",
"idempotencyKey": "7a3e2c1d-9f4b-4f7a-8e1a-12bd4f3a7c90",
"reference": "deposit-2026-04-07",
"description": "Initial deposit for client 42",
"status": "Posted",
"reversalOf": null,
"createdBy": "ops@acme-finance.com",
"metadata": { "channel": "web" },
"postedAt": "2026-04-07T15:33:02.114Z",
"lines": [
{
"id": "el_01HZYX4K2M8Q5R3T9VB6WC0JH",
"accountId": "acc_01HZYX3T5K7M9P4Q8R2V6WB0J0",
"accountCode": "PLATFORM-FLOAT",
"entryType": "Debit",
"amount": 50000,
"currency": "GHS",
"description": "Initial deposit"
},
{
"id": "el_01HZYX4K2M8Q5R3T9VB6WC0JI",
"accountId": "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
"accountCode": "CLIENT-42",
"entryType": "Credit",
"amount": 50000,
"currency": "GHS",
"description": "Initial deposit"
}
]
}Prop
Type
EntryLine shape
Prop
Type
The balancing rule
For each distinct currency present in the lines:
sum(debits) === sum(credits)An entry that touches multiple currencies must balance independently in
each. You cannot net a USD debit against a GHS credit. If the rule is
violated, the post is rejected with 422 and nothing is written.
Multi-currency entries are allowed. A single entry can debit
PLATFORM-FLOAT in GHS and credit a different account in GHS, while also
debiting a USD settlement account and crediting another USD account, as
long as each currency balances on its own.
Post a journal entry
/api/v1/ledger/journal-entriesIdempotency-Keyatomically posts a balanced entry.
Request body
Prop
Type
Each element of lines has:
Prop
Type
What the engine validates
In order:
Idempotency-Keyheader is present.- Each
accountCoderesolves to an active account in the current tenant. - Every line's
amountis strictly positive. - Per-currency debits equal per-currency credits.
- For each Asset account that is debited, the new ledger balance does not drop below zero. Liability, Equity, Revenue, and Expense accounts are allowed to go negative, that is normal double-entry behaviour (e.g. crediting a fresh liability account from zero is expected).
If all checks pass, the entry is written, balances are updated, and per-account transaction log rows are created: all atomically.
Response
201 Created with the full JournalEntry including resolved id values
for each line.
curl -X POST https://api.shiwake.example.com/api/v1/ledger/journal-entries \
-H "X-Api-Key: sk_live_..." \
-H "Idempotency-Key: 7a3e2c1d-9f4b-4f7a-8e1a-12bd4f3a7c90" \
-H "Content-Type: application/json" \
-d '{
"reference": "deposit-2026-04-07",
"description": "Initial deposit for client 42",
"createdBy": "ops@acme-finance.com",
"lines": [
{ "accountCode": "PLATFORM-FLOAT", "entryType": "Debit", "amount": 50000, "description": "Initial deposit" },
{ "accountCode": "CLIENT-42", "entryType": "Credit", "amount": 50000, "description": "Initial deposit" }
]
}'Insufficient balance
When a debit would drive an account's ledger balance below zero (and the
account's normalBalance configuration disallows it), the engine rejects
the post with 422 and returns an InsufficientBalanceDetail in the data
field so the client can react programmatically.
{
"code": 422,
"message": "Insufficient balance on account 'PLATFORM-FLOAT'. Current: 0, Required: 50000, Shortfall: 50000.",
"data": null
}This check only fires on Asset accounts. Crediting a Liability account that has a zero balance is valid. The balance simply goes negative, representing money the platform owes.
Status codes
| Code | Meaning |
|---|---|
201 | Entry posted |
400 | Missing Idempotency-Key, malformed body, non-positive amounts |
404 | One of the referenced accountCode values does not exist |
422 | Lines don't balance, account is inactive, insufficient balance |
Get a journal entry
/api/v1/ledger/journal-entries/{entryId}Returns the full entry including all lines. Useful for reading back something you just posted or for audit trails.
curl https://api.shiwake.example.com/api/v1/ledger/journal-entries/je_01HZYX4K2M8Q5R3T9VB6WC0JG \
-H "X-Api-Key: sk_live_..."Status codes
| Code | Meaning |
|---|---|
200 | Entry found |
404 | No entry with that id in the current tenant |
List journal entries
/api/v1/ledger/journal-entriescursor-paginated, sorted by postedAt descending.
Returns a lightweight list (one row per entry without the nested lines) optimized for dashboards and audit UIs that render many rows at once. Fetch the full entry with Get a journal entry when you need the line detail.
Query parameters
Prop
Type
List item shape
Prop
Type
curl "https://api.shiwake.example.com/api/v1/ledger/journal-entries?status=Posted&size=50" \
-H "X-Api-Key: sk_live_..."Reverse a journal entry
/api/v1/ledger/journal-entries/{entryId}/reverseIdempotency-Keycreates a compensating entry.
Reversal does not edit or delete the original entry. Instead, the engine
creates a new journal entry with every line's entryType flipped:
debits become credits and vice versa. The new entry's reversalOf field
points at the original, and the original's status transitions from
Posted to Reversed.
The compensating entry posts exactly the same way any other entry would. It is subject to the same balance checks, writes transaction log rows, and
updates account balances. If the reversal would itself violate a balance
check (e.g. the target account has since been drained), it returns 422
just like any other post.
Request body
Prop
Type
Response
201 Created with the new compensating entry. The response carries the new
entry's id, not the original's.
curl -X POST https://api.shiwake.example.com/api/v1/ledger/journal-entries/je_01HZYX4K2M8Q5R3T9VB6WC0JG/reverse \
-H "X-Api-Key: sk_live_..." \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"reason": "Customer disputed transaction",
"createdBy": "support@acme-finance.com"
}'Status codes
| Code | Meaning |
|---|---|
201 | Reversal entry posted |
400 | Missing Idempotency-Key, malformed body |
404 | Original entry not found |
409 | Original entry is already reversed |
422 | Reversal would violate a balance check |
Reversal is not "undo". The original entry stays in the ledger forever. Its status changes to Reversed but its lines are never deleted. Audit
trails reading the journal entries table see both the original and the
compensating entry, linked via reversalOf.
Last updated on