# Accounts

Create accounts, read balances, and list per-account transactions.

URL: https://docs.shiwake.app/docs/api/accounts



Accounts are the containers that debits and credits land on. Every account
belongs to one tenant, has a stable `code` that your application chooses, a
currency, and a type that determines its normal balance.

All endpoints on this page live under `/api/v1/ledger/accounts` and require
an [`X-Api-Key`](/docs/api/authentication) header. Mutating endpoints
additionally require an [`Idempotency-Key`](/docs/api/idempotency).

The Account object [#the-account-object]

```json
{
  "id": "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
  "code": "CLIENT-42",
  "name": "Customer 42 Wallet",
  "accountType": "Liability",
  "normalBalance": "Credit",
  "parentId": null,
  "currency": "GHS",
  "isActive": true,
  "ledgerBalance": 50000,
  "availableBalance": 50000,
  "version": 3,
  "metadata": { "clientId": "42" },
  "createdAt": "2026-04-01T09:12:44.318Z",
  "updatedAt": "2026-04-07T15:33:02.114Z"
}
```

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Server-assigned identifier, stable for the lifetime of the account&#x22; },
  code: { type: &#x22;string&#x22;, required: true, description: &#x22;Client-chosen stable identifier, unique within the tenant. Used to reference the account in journal entry lines&#x22; },
  name: { type: &#x22;string&#x22;, required: true, description: &#x22;Human-readable label&#x22; },
  accountType: { type: &#x22;enum&#x22;, required: true, description: <>One of <code>Asset</code>, <code>Liability</code>, <code>Equity</code>, <code>Revenue</code>, <code>Expense</code></> },
  normalBalance: { type: &#x22;enum&#x22;, required: true, description: <><code>Debit</code> or <code>Credit</code>. Determines which side increases the balance</> },
  parentId: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Optional parent account id, for building account hierarchies&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: <>ISO 4217 currency code (e.g. <code>GHS</code>, <code>USD</code>, <code>EUR</code>). Lines posted to this account must match</> },
  isActive: { type: &#x22;bool&#x22;, required: true, description: <><code>false</code> if the account has been deactivated</> },
  ledgerBalance: { type: &#x22;long&#x22;, required: true, description: &#x22;Settled balance in minor units (e.g. pesewas for GHS)&#x22; },
  availableBalance: { type: &#x22;long&#x22;, required: true, description: <><code>ledgerBalance</code> minus any active holds</> },
  version: { type: &#x22;int&#x22;, required: true, description: &#x22;Optimistic-concurrency counter incremented on every balance change&#x22; },
  metadata: { type: &#x22;object | null&#x22;, required: true, description: &#x22;Free-form JSON that your application can attach&#x22; },
  createdAt: { type: &#x22;datetime&#x22;, required: true, description: &#x22;UTC timestamp of account creation&#x22; },
  updatedAt: { type: &#x22;datetime | null&#x22;, required: true, description: <>UTC timestamp of the last mutation, <code>null</code> if never modified</> },
}"
/>

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

The combination of `accountType` and `normalBalance` determines how balances
grow. The conventional mapping (which Shiwake does **not** enforce, you
can pick whatever you need) is:

| Type        | Normal balance | Debits   | Credits  |
| ----------- | -------------- | -------- | -------- |
| `Asset`     | `Debit`        | Increase | Decrease |
| `Expense`   | `Debit`        | Increase | Decrease |
| `Liability` | `Credit`       | Decrease | Increase |
| `Equity`    | `Credit`       | Decrease | Increase |
| `Revenue`   | `Credit`       | Decrease | Increase |

<Callout type="info">
  Shiwake stores balances as signed integers in minor units. **Asset** accounts
  enforce a non-negative balance: debiting an Asset below zero returns `422`.
  All other account types (Liability, Equity, Revenue, Expense) may go negative,
  which is normal double-entry behaviour (e.g. crediting a Liability from zero
  means the platform owes that amount).
</Callout>

Ledger vs available balance [#ledger-vs-available-balance]

* **Ledger balance** reflects money that has settled: the net of all posted
  journal entry lines.
* **Available balance** is `ledgerBalance` minus any active
  [holds](/docs/api/holds). Use it when deciding whether a new debit is
  safe to attempt.

***

Create an account [#create-an-account]

<Endpoint method="POST" path="/api/v1/ledger/accounts">
  creates an account in the current tenant.
</Endpoint>

Request body [#request-body]

<TypeTable
  type="{
  code: { type: &#x22;string&#x22;, required: true, description: <>Unique within the tenant. Conflicts return <code>409</code></> },
  name: { type: &#x22;string&#x22;, required: true, description: &#x22;Human-readable label&#x22; },
  accountType: { type: &#x22;enum&#x22;, required: true, description: <><code>Asset</code>, <code>Liability</code>, <code>Equity</code>, <code>Revenue</code>, or <code>Expense</code></> },
  normalBalance: { type: &#x22;enum&#x22;, required: true, description: <><code>Debit</code> or <code>Credit</code></> },
  parentId: { type: &#x22;string&#x22;, description: &#x22;Optional parent account id&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  metadata: { type: &#x22;object&#x22;, description: &#x22;Arbitrary JSON stored alongside the account&#x22; },
}"
/>

Response [#response]

`201 Created` with the new account inside the envelope.

<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/accounts \
      -H "X-Api-Key: sk_live_..." \
      -H "Idempotency-Key: 7a3e2c1d-9f4b-4f7a-8e1a-12bd4f3a7c90" \
      -H "Content-Type: application/json" \
      -d '{
        "code": "CLIENT-42",
        "name": "Customer 42 Wallet",
        "accountType": "Liability",
        "normalBalance": "Credit",
        "currency": "GHS",
        "metadata": { "clientId": "42" }
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var account = await ledger.CreateAccountAsync(new CreateAccountRequest
    {
        Code          = "CLIENT-42",
        Name          = "Customer 42 Wallet",
        AccountType   = "Liability",
        NormalBalance = "Credit",
        Currency      = "GHS"
    }, idempotencyKey: Guid.NewGuid().ToString());
    ```
  </CodeBlockTab>

  <CodeBlockTab value="response">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "id": "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
        "code": "CLIENT-42",
        "name": "Customer 42 Wallet",
        "accountType": "Liability",
        "normalBalance": "Credit",
        "parentId": null,
        "currency": "GHS",
        "isActive": true,
        "ledgerBalance": 0,
        "availableBalance": 0,
        "version": 0,
        "metadata": { "clientId": "42" },
        "createdAt": "2026-04-07T15:33:02.114Z",
        "updatedAt": null
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes]

| Code  | Meaning                                                |
| ----- | ------------------------------------------------------ |
| `201` | Account created                                        |
| `400` | Missing `Idempotency-Key`, malformed body              |
| `401` | Missing or invalid API key                             |
| `409` | Another account in this tenant already has this `code` |

***

Get an account [#get-an-account]

<Endpoint method="GET" path="/api/v1/ledger/accounts/{accountId}" />

Returns the account including its current balances. `{accountId}` is the
server-assigned `id`, not the `code`.

<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/accounts/acc_01HZYX3T5K7M9P4Q8R2V6WB0JE \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var account = await ledger.GetAccountAsync("acc_01HZYX3T5K7M9P4Q8R2V6WB0JE");
    ```
  </CodeBlockTab>

  <CodeBlockTab value="response">
    ```json
    {
      "code": 200,
      "message": "Retrieved successfully",
      "data": {
        "id": "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
        "code": "CLIENT-42",
        "name": "Customer 42 Wallet",
        "accountType": "Liability",
        "normalBalance": "Credit",
        "currency": "GHS",
        "isActive": true,
        "ledgerBalance": 50000,
        "availableBalance": 50000,
        "version": 3,
        "createdAt": "2026-04-01T09:12:44.318Z",
        "updatedAt": "2026-04-07T15:33:02.114Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes-1]

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

***

List accounts [#list-accounts]

<Endpoint method="GET" path="/api/v1/ledger/accounts">
  [cursor-paginated](/docs/api/pagination),
  sorted by `code` ascending.
</Endpoint>

Query parameters [#query-parameters]

<TypeTable
  type="{
  accountType: { type: &#x22;enum&#x22;, description: <>Filter to one type (<code>Asset</code>, <code>Liability</code>, <code>Equity</code>, <code>Revenue</code>, <code>Expense</code>)</> },
  parentId: { type: &#x22;string&#x22;, description: &#x22;Filter to children of a specific parent account&#x22; },
  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></> },
}"
/>

<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/accounts?accountType=Liability&size=50" \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var page = await ledger.ListAccountsAsync(
        accountType: "Liability",
        size: 50);

    foreach (var account in page.Accounts)
    {
        Console.WriteLine($"{account.Code}: {account.LedgerBalance}");
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="response">
    ```json
    {
      "code": 200,
      "message": "Retrieved successfully",
      "data": {
        "accounts": [
          {
            "id": "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
            "code": "CLIENT-42",
            "name": "Customer 42 Wallet",
            "accountType": "Liability",
            "normalBalance": "Credit",
            "currency": "GHS",
            "isActive": true,
            "ledgerBalance": 50000,
            "availableBalance": 50000,
            "version": 3,
            "createdAt": "2026-04-01T09:12:44.318Z",
            "updatedAt": "2026-04-07T15:33:02.114Z"
          }
        ],
        "next_cursor": "CLIENT-42|acc_01HZYX3T5K7M9P4Q8R2V6WB0JE"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

***

Deactivate an account [#deactivate-an-account]

<Endpoint method="POST" path="/api/v1/ledger/accounts/{accountId}/deactivate">
  soft-delete.
</Endpoint>

Marks the account as inactive. Deactivated accounts stay in the database and
remain queryable for historical reporting, but reject new journal entry
lines.

The engine enforces one precondition: **the ledger balance must be zero**.
If there is any outstanding balance, the call returns `422` with a message
explaining the current balance and you must drain the account first.

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

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

    <CodeBlockTabsTrigger value="error">
      422 Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X POST https://api.shiwake.example.com/api/v1/ledger/accounts/acc_01HZYX3T5K7M9P4Q8R2V6WB0JE/deactivate \
      -H "X-Api-Key: sk_live_..." \
      -H "Idempotency-Key: $(uuidgen)"
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var account = await ledger.DeactivateAccountAsync(
        "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
        idempotencyKey: Guid.NewGuid().ToString());
    ```
  </CodeBlockTab>

  <CodeBlockTab value="error">
    ```json
    {
      "code": 422,
      "message": "Cannot deactivate account 'CLIENT-42': ledger balance is 15000 (minor units).",
      "data": null
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes-2]

| Code  | Meaning                        |
| ----- | ------------------------------ |
| `200` | Account deactivated            |
| `404` | Account not found              |
| `409` | Account is already deactivated |
| `422` | Ledger balance is non-zero     |

***

Get balance [#get-balance]

<Endpoint method="GET" path="/api/v1/ledger/accounts/{accountId}/balance">
  lightweight balance read.
</Endpoint>

Use this when you only need the current balances and not the full account
metadata. Returns a slim payload that is cheaper to fetch and easier to
cache.

Response [#response-1]

<TypeTable
  type="{
  accountId: { type: &#x22;string&#x22;, required: true, description: &#x22;Account id&#x22; },
  code: { type: &#x22;string&#x22;, required: true, description: &#x22;Account code&#x22; },
  name: { type: &#x22;string&#x22;, required: true, description: &#x22;Account name&#x22; },
  ledgerBalance: { type: &#x22;long&#x22;, required: true, description: &#x22;Settled balance in minor units&#x22; },
  availableBalance: { type: &#x22;long&#x22;, required: true, description: &#x22;Ledger balance minus active holds&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  version: { type: &#x22;int&#x22;, required: true, description: &#x22;Optimistic-concurrency counter&#x22; },
  asOf: { type: &#x22;datetime&#x22;, required: true, description: &#x22;UTC timestamp when the balance was read&#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/accounts/acc_01HZYX3T5K7M9P4Q8R2V6WB0JE/balance \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var balance = await ledger.GetBalanceAsync("acc_01HZYX3T5K7M9P4Q8R2V6WB0JE");
    Console.WriteLine($"Ledger: {balance.LedgerBalance}, Available: {balance.AvailableBalance}");
    ```
  </CodeBlockTab>

  <CodeBlockTab value="response">
    ```json
    {
      "code": 200,
      "message": "Retrieved successfully",
      "data": {
        "accountId": "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
        "code": "CLIENT-42",
        "name": "Customer 42 Wallet",
        "ledgerBalance": 50000,
        "availableBalance": 50000,
        "currency": "GHS",
        "version": 3,
        "asOf": "2026-04-07T15:33:02.114Z"
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

***

List transactions [#list-transactions]

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

Returns the per-account transaction log: one row per entry line that hit
this account. Each row carries the running balance at the moment of posting,
computed and stored atomically with the journal entry, so you get a
point-in-time snapshot without recomputing history.

Query parameters [#query-parameters-1]

<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</> },
  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></> },
}"
/>

Transaction shape [#transaction-shape]

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Transaction id&#x22; },
  accountId: { type: &#x22;string&#x22;, required: true, description: &#x22;The account this row belongs to&#x22; },
  journalEntryId: { type: &#x22;string&#x22;, required: true, description: &#x22;The parent journal entry&#x22; },
  entryLineId: { type: &#x22;string&#x22;, required: true, description: &#x22;The specific line within the journal entry&#x22; },
  direction: { type: &#x22;enum&#x22;, required: true, description: <><code>Debit</code> or <code>Credit</code>: the side of this line</> },
  amount: { type: &#x22;long&#x22;, required: true, description: &#x22;Line amount in minor units&#x22; },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  runningBalance: { type: &#x22;long&#x22;, required: true, description: &#x22;Ledger balance immediately after this line was applied&#x22; },
  reference: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Inherited from the journal entry&#x22; },
  description: { type: &#x22;string | null&#x22;, required: true, description: &#x22;Inherited from the journal entry line&#x22; },
  metadata: { type: &#x22;object | null&#x22;, required: true, description: &#x22;Inherited from the journal entry&#x22; },
  postedAt: { type: &#x22;datetime&#x22;, required: true, description: &#x22;UTC timestamp of the journal entry&#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/accounts/acc_01HZYX3T5K7M9P4Q8R2V6WB0JE/transactions?size=20" \
      -H "X-Api-Key: sk_live_..."
    ```
  </CodeBlockTab>

  <CodeBlockTab value="csharp">
    ```csharp
    var page = await ledger.GetTransactionsAsync(
        "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
        from: DateTime.UtcNow.AddDays(-30),
        size: 50);

    foreach (var tx in page.Transactions)
    {
        Console.WriteLine($"{tx.PostedAt:o}  {tx.Direction,-6}  {tx.Amount}  running={tx.RunningBalance}");
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="response">
    ```json
    {
      "code": 200,
      "message": "Retrieved successfully",
      "data": {
        "account_id": "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
        "code": "CLIENT-42",
        "name": "Customer 42 Wallet",
        "currency": "GHS",
        "transactions": [
          {
            "id": "txn_01HZYX4K2M8Q5R3T9VB6WC0JF",
            "accountId": "acc_01HZYX3T5K7M9P4Q8R2V6WB0JE",
            "journalEntryId": "je_01HZYX4K2M8Q5R3T9VB6WC0JG",
            "entryLineId": "el_01HZYX4K2M8Q5R3T9VB6WC0JH",
            "direction": "Credit",
            "amount": 50000,
            "currency": "GHS",
            "runningBalance": 50000,
            "reference": "deposit-2026-04-07",
            "description": "Initial deposit",
            "metadata": null,
            "postedAt": "2026-04-07T15:33:02.114Z"
          }
        ],
        "next_cursor": null
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>
