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:
| 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 |
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
ledgerBalanceminus any active holds. Use it when deciding whether a new debit is safe to attempt.
Create an account
/api/v1/ledger/accountsIdempotency-Keycreates 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
| 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
/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
| Code | Meaning |
|---|---|
200 | Account found |
404 | No account with that id in the current tenant |
List accounts
/api/v1/ledger/accountscursor-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
/api/v1/ledger/accounts/{accountId}/deactivateIdempotency-Keysoft-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
| Code | Meaning |
|---|---|
200 | Account deactivated |
404 | Account not found |
409 | Account is already deactivated |
422 | Ledger balance is non-zero |
Get balance
/api/v1/ledger/accounts/{accountId}/balancelightweight 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
/api/v1/ledger/accounts/{accountId}/transactionscursor-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_..."Last updated on