ShiwakeDocs

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

POST/api/v1/ledger/journal-entriesIdempotency-Key

atomically posts a balanced entry.

Request body

Prop

Type

Each element of lines has:

Prop

Type

What the engine validates

In order:

  1. Idempotency-Key header is present.
  2. Each accountCode resolves to an active account in the current tenant.
  3. Every line's amount is strictly positive.
  4. Per-currency debits equal per-currency credits.
  5. 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

CodeMeaning
201Entry posted
400Missing Idempotency-Key, malformed body, non-positive amounts
404One of the referenced accountCode values does not exist
422Lines don't balance, account is inactive, insufficient balance

Get a journal entry

GET/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

CodeMeaning
200Entry found
404No entry with that id in the current tenant

List journal entries

GET/api/v1/ledger/journal-entries

cursor-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

POST/api/v1/ledger/journal-entries/{entryId}/reverseIdempotency-Key

creates 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

CodeMeaning
201Reversal entry posted
400Missing Idempotency-Key, malformed body
404Original entry not found
409Original entry is already reversed
422Reversal 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.

Edit on GitHub

Last updated on

On this page