ShiwakeDocs

Accounts

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

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 header. Mutating endpoints additionally require an Idempotency-Key.

The Account object

{
  "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"
}

Prop

Type

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:

TypeNormal balanceDebitsCredits
AssetDebitIncreaseDecrease
ExpenseDebitIncreaseDecrease
LiabilityCreditDecreaseIncrease
EquityCreditDecreaseIncrease
RevenueCreditDecreaseIncrease

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

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. Use it when deciding whether a new debit is safe to attempt.

Create an account

POST/api/v1/ledger/accountsIdempotency-Key

creates an account in the current tenant.

Request body

Prop

Type

Response

201 Created with the new account inside the envelope.

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" }
  }'

Status codes

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

Get an account

GET/api/v1/ledger/accounts/{accountId}

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

curl https://api.shiwake.example.com/api/v1/ledger/accounts/acc_01HZYX3T5K7M9P4Q8R2V6WB0JE \
  -H "X-Api-Key: sk_live_..."

Status codes

CodeMeaning
200Account found
404No account with that id in the current tenant

List accounts

GET/api/v1/ledger/accounts

cursor-paginated, sorted by code ascending.

Query parameters

Prop

Type

curl "https://api.shiwake.example.com/api/v1/ledger/accounts?accountType=Liability&size=50" \
  -H "X-Api-Key: sk_live_..."

Deactivate an account

POST/api/v1/ledger/accounts/{accountId}/deactivateIdempotency-Key

soft-delete.

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.

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

Status codes

CodeMeaning
200Account deactivated
404Account not found
409Account is already deactivated
422Ledger balance is non-zero

Get balance

GET/api/v1/ledger/accounts/{accountId}/balance

lightweight balance read.

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

Prop

Type

curl https://api.shiwake.example.com/api/v1/ledger/accounts/acc_01HZYX3T5K7M9P4Q8R2V6WB0JE/balance \
  -H "X-Api-Key: sk_live_..."

List transactions

GET/api/v1/ledger/accounts/{accountId}/transactions

cursor-paginated, sorted by postedAt descending.

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

Prop

Type

Transaction shape

Prop

Type

curl "https://api.shiwake.example.com/api/v1/ledger/accounts/acc_01HZYX3T5K7M9P4Q8R2V6WB0JE/transactions?size=20" \
  -H "X-Api-Key: sk_live_..."
Edit on GitHub

Last updated on

On this page