ShiwakeDocs

Reconciliation

Trial balance and stored-vs-computed balance verification.

Reconciliation endpoints let you audit the ledger: confirm the books balance, and that cached account balances agree with the underlying entry lines. These are read-only and safe to run at any time.

Trial balance

GET/api/v1/ledger/reconciliation/trial-balance

Returns total debits and credits per account, computed fresh from posted journal entry lines. Grand totals must be equal for the books to balance. If they aren't, something has gone very wrong upstream (the engine enforces balancing on post, so this should always be true in practice).

Query parameters

Prop

Type

curl "https://api.shiwake.example.com/api/v1/ledger/reconciliation/trial-balance?asOf=2026-04-07T23:59:59Z" \
  -H "X-Api-Key: sk_live_..."

Response fields

Prop

Type


Verify balances

GET/api/v1/ledger/reconciliation/verify-balances

Compares the cached account_balances table against balances computed fresh from entry_lines. The cached values are kept in sync on every post, so they should always match. This endpoint catches storage corruption, failed migrations, or bugs in the posting path.

Returns 200 when every account matches, 422 when any discrepancy is found.

curl "https://api.shiwake.example.com/api/v1/ledger/reconciliation/verify-balances" \
  -H "X-Api-Key: sk_live_..."

Response fields

Prop

Type

A 422 from this endpoint is a ledger integrity alert. Stop writing to the tenant, snapshot the database, and investigate before resuming. Do not "fix" a discrepancy by overwriting the stored balance: find the root cause first.

Running reconciliation on a schedule

Most teams run verify-balances as a scheduled job (nightly for low-volume tenants, hourly for high-volume ones) and page on any 422. The endpoint is not rate-limited separately, so it counts against the tenant's 200 req/min budget; a single call is enough.

Edit on GitHub

Last updated on

On this page