# Journal Entries

Post, read, list, and reverse balanced double-entry journal entries.

URL: https://docs.shiwake.app/docs/api/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](/docs/api/accounts#list-transactions)
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`](/docs/api/authentication) header. Mutating endpoints
additionally require an [`Idempotency-Key`](/docs/api/idempotency).

The JournalEntry object [#the-journalentry-object]

```json
{
  "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"
    }
  ]
}
```

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Server-assigned identifier&#x22; },
  idempotencyKey: { type: &#x22;string&#x22;, required: true, description: &#x22;The key the caller provided when posting&#x22; },
  reference: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Optional external reference, searchable&#x22; },
  description: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Human-readable note for the whole entry&#x22; },
  status: { type: &#x22;enum&#x22;, required: true, description: <><code>Posted</code> or <code>Reversed</code></> },
  reversalOf: { type: &#x22;string | null&#x22;, required: true, description: &#x22;If this entry reverses another, the original entry's id&#x22; },
  createdBy: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Free-form actor identifier supplied by the caller&#x22; },
  metadata: { type: &#x22;object | null&#x22;, required: true, description: &#x22;Arbitrary JSON attached by the caller&#x22; },
  postedAt: { type: &#x22;datetime&#x22;, required: true, description: &#x22;UTC timestamp when the entry was committed&#x22; },
  lines: { type: &#x22;EntryLine[]&#x22;, required: true, description: &#x22;Two or more balanced lines&#x22; },
}"
/>

EntryLine shape [#entryline-shape]

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Line id&#x22; },
  accountId: { type: &#x22;string&#x22;, required: true, description: &#x22;Resolved account id&#x22; },
  accountCode: { type: &#x22;string&#x22;, required: true, description: <>The <code>code</code> the caller referenced in the request</> },
  entryType: { type: &#x22;enum&#x22;, required: true, description: <><code>Debit</code> or <code>Credit</code></> },
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Line amount in minor units. Must be positive&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;Inherited from the referenced account&#x22; },
  description: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Optional per-line note&#x22; },
}"
/>

The balancing rule [#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.

<Callout type="info">
  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.
</Callout>

***

Post a journal entry [#post-a-journal-entry]

<Endpoint method="POST" path="/api/v1/ledger/journal-entries">
  atomically posts a balanced entry.
</Endpoint>

Request body [#request-body]

<TypeTable
  type="{
  reference: { type: &#x22;string&#x22;, description: &#x22;Optional external reference&#x22; },
  description: { type: &#x22;string&#x22;, description: &#x22;Entry-level description&#x22; },
  createdBy: { type: &#x22;string&#x22;, description: &#x22;Actor identifier for audit trails&#x22; },
  metadata: { type: &#x22;object&#x22;, description: &#x22;Arbitrary JSON&#x22; },
  lines: { type: &#x22;EntryLineRequest[]&#x22;, required: true, description: &#x22;Two or more lines that balance per currency&#x22; },
}"
/>

Each element of `lines` has:

<TypeTable
  type="{
  accountCode: { type: &#x22;string&#x22;, required: true, description: <>Account <code>code</code> (not <code>id</code>). Must exist and be active</> },
  entryType: { type: &#x22;enum&#x22;, required: true, description: <><code>Debit</code> or <code>Credit</code></> },
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Positive integer in minor units&#x22; },
  description: { type: &#x22;string&#x22;, description: &#x22;Per-line description&#x22; },
}"
/>

What the engine validates [#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 [#response]

`201 Created` with the full `JournalEntry` including resolved `id` values
for each line.

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="response">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    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" }
        ]
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var entry = await ledger.PostJournalEntryAsync(new PostJournalEntryRequest
    {
        Reference   = "deposit-2026-04-07",
        Description = "Initial deposit for client 42",
        CreatedBy   = "ops@acme-finance.com",
        Lines =
        [
            new("PLATFORM-FLOAT", "Debit",  50_000, "Initial deposit"),
            new("CLIENT-42",      "Credit", 50_000, "Initial deposit")
        ]
    }, idempotencyKey: Guid.NewGuid().ToString());

    Console.WriteLine($"Posted entry {entry.Id} with {entry.Lines.Count} lines");
    ```
  </CodeBlockTab>

  <CodeBlockTab value="response">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "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": null,
        "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"
          }
        ]
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Insufficient balance [#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.

```json
{
  "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 [#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 [#get-a-journal-entry]

<Endpoint method="GET" path="/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.

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl https://api.shiwake.example.com/api/v1/ledger/journal-entries/je_01HZYX4K2M8Q5R3T9VB6WC0JG \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var entry = await ledger.GetJournalEntryAsync("je_01HZYX4K2M8Q5R3T9VB6WC0JG");
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes-1]

| Code  | Meaning                                     |
| ----- | ------------------------------------------- |
| `200` | Entry found                                 |
| `404` | No entry with that id in the current tenant |

***

List journal entries [#list-journal-entries]

<Endpoint method="GET" path="/api/v1/ledger/journal-entries">
  [cursor-paginated](/docs/api/pagination), sorted by `postedAt` descending.
</Endpoint>

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](#get-a-journal-entry) when you
need the line detail.

Query parameters [#query-parameters]

<TypeTable
  type="{
  from: { type: &#x22;datetime&#x22;, description: <>Lower bound on <code>postedAt</code>, inclusive</> },
  to: { type: &#x22;datetime&#x22;, description: <>Upper bound on <code>postedAt</code>, inclusive</> },
  status: { type: &#x22;enum&#x22;, description: <><code>Posted</code> or <code>Reversed</code></> },
  cursor: { type: &#x22;string&#x22;, description: <>Cursor from the previous page's <code>next_cursor</code></> },
  size: { type: &#x22;int&#x22;, description: <>Page size, <code>1..200</code>, default <code>50</code></> },
}"
/>

List item shape [#list-item-shape]

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Entry id&#x22; },
  idempotencyKey: { type: &#x22;string&#x22;, required: true, description: &#x22;Idempotency key provided when posting&#x22; },
  reference: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Optional external reference&#x22; },
  description: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Entry description&#x22; },
  status: { type: &#x22;enum&#x22;, required: true, description: <><code>Posted</code> or <code>Reversed</code></> },
  lineCount: { type: &#x22;int&#x22;, required: true, description: &#x22;Number of lines in the entry&#x22; },
  totalAmount: { type: &#x22;long&#x22;, required: true, description: &#x22;Sum of all debit lines in minor units&#x22; },
  postedAt: { type: &#x22;datetime&#x22;, required: true, description: &#x22;UTC timestamp&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="response">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl "https://api.shiwake.example.com/api/v1/ledger/journal-entries?status=Posted&size=50" \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var page = await ledger.ListJournalEntriesAsync(
        from: DateTime.UtcNow.Date,
        status: "Posted",
        size: 50);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="response">
    ```json
    {
      "code": 200,
      "message": "Retrieved successfully",
      "data": {
        "entries": [
          {
            "id": "je_01HZYX4K2M8Q5R3T9VB6WC0JG",
            "idempotencyKey": "7a3e2c1d-9f4b-4f7a-8e1a-12bd4f3a7c90",
            "reference": "deposit-2026-04-07",
            "description": "Initial deposit for client 42",
            "status": "Posted",
            "lineCount": 2,
            "totalAmount": 50000,
            "postedAt": "2026-04-07T15:33:02.114Z"
          }
        ],
        "next_cursor": null
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

***

Reverse a journal entry [#reverse-a-journal-entry]

<Endpoint method="POST" path="/api/v1/ledger/journal-entries/{entryId}/reverse">
  creates a
  compensating entry.
</Endpoint>

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 [#request-body-1]

<TypeTable
  type="{
  reason: { type: &#x22;string&#x22;, description: <>Human-readable reason, stored on the new entry's <code>description</code></> },
  createdBy: { type: &#x22;string&#x22;, description: &#x22;Actor identifier for audit trails&#x22; },
}"
/>

Response [#response-1]

`201 Created` with the new compensating entry. The response carries the new
entry's `id`, not the original's.

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="csharp">
      C# (SDK)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="response">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    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"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var reversal = await ledger.ReverseJournalEntryAsync(
        "je_01HZYX4K2M8Q5R3T9VB6WC0JG",
        new ReverseEntryRequest
        {
            Reason    = "Customer disputed transaction",
            CreatedBy = "support@acme-finance.com"
        },
        idempotencyKey: Guid.NewGuid().ToString());

    Console.WriteLine($"Reversal entry: {reversal.Id}, reversalOf: {reversal.ReversalOf}");
    ```
  </CodeBlockTab>

  <CodeBlockTab value="response">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "id": "je_01HZYX9M4N7Q6S3U8VB5WC0JK",
        "idempotencyKey": "f2e7b3c4-1a9d-4e6b-8c7a-23ce5f4b8d91",
        "reference": null,
        "description": "Reversal: Customer disputed transaction",
        "status": "Posted",
        "reversalOf": "je_01HZYX4K2M8Q5R3T9VB6WC0JG",
        "createdBy": "support@acme-finance.com",
        "postedAt": "2026-04-07T16:05:19.721Z",
        "lines": [
          {
            "accountCode": "PLATFORM-FLOAT",
            "entryType": "Credit",
            "amount": 50000,
            "currency": "GHS"
          },
          {
            "accountCode": "CLIENT-42",
            "entryType": "Debit",
            "amount": 50000,
            "currency": "GHS"
          }
        ]
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes-2]

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

<Callout type="warn">
  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`.
</Callout>
