# Reconciliation

Trial balance and stored-vs-computed balance verification.

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



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 [#trial-balance]

<Endpoint method="GET" path="/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 [#query-parameters]

<TypeTable
  type="{
  asOf: { type: &#x22;datetime&#x22;, description: &#x22;Include entries posted at or before this timestamp. Omit for \&#x22;now\&#x22;&#x22; },
}"
/>

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

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

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

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

  <CodeBlockTab value="csharp">
    ```csharp
    var trial = await ledger.GetTrialBalanceAsync(
        asOf: new DateTime(2026, 4, 7, 23, 59, 59, DateTimeKind.Utc));

    if (!trial.IsBalanced)
        logger.LogCritical("Trial balance off by {Diff}",
            trial.GrandTotalDebits - trial.GrandTotalCredits);
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "message": "Retrieved successfully",
      "data": {
        "asOf": "2026-04-07T23:59:59Z",
        "rows": [
          {
            "accountId": "acc_01HZ...",
            "accountCode": "PLATFORM-FLOAT",
            "accountName": "Platform float",
            "accountType": "Asset",
            "normalBalance": "Debit",
            "totalDebits": 1200000,
            "totalCredits": 275000,
            "netBalance": 925000
          },
          {
            "accountId": "acc_01HZ...",
            "accountCode": "CLIENT-42",
            "accountName": "Acme Retail",
            "accountType": "Liability",
            "normalBalance": "Credit",
            "totalDebits": 50000,
            "totalCredits": 200000,
            "netBalance": -150000
          }
        ],
        "grandTotalDebits": 1250000,
        "grandTotalCredits": 1250000,
        "isBalanced": true
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Response fields [#response-fields]

<TypeTable
  type="{
  asOf: { type: &#x22;datetime&#x22;, required: true, description: &#x22;Cutoff used for the computation&#x22; },
  rows: { type: &#x22;array&#x22;, required: true, description: &#x22;One row per account with non-zero activity&#x22; },
  &#x22;rows[].totalDebits&#x22;: { type: &#x22;long&#x22;, required: true, description: &#x22;Sum of debit lines, minor units&#x22; },
  &#x22;rows[].totalCredits&#x22;: { type: &#x22;long&#x22;, required: true, description: &#x22;Sum of credit lines, minor units&#x22; },
  &#x22;rows[].netBalance&#x22;: { type: &#x22;long&#x22;, required: true, description: <><code>debits − credits</code>. Positive = debit-heavy</> },
  grandTotalDebits: { type: &#x22;long&#x22;, required: true, description: &#x22;Sum across all accounts&#x22; },
  grandTotalCredits: { type: &#x22;long&#x22;, required: true, description: &#x22;Sum across all accounts&#x22; },
  isBalanced: { type: &#x22;bool&#x22;, required: true, description: <><code>grandTotalDebits == grandTotalCredits</code></> },
}"
/>

***

Verify balances [#verify-balances]

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

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

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

    <CodeBlockTabsTrigger value="json">
      Response (200)
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json422">
      Response (422)
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

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

  <CodeBlockTab value="csharp">
    ```csharp
    try
    {
        var result = await ledger.VerifyBalancesAsync();
        logger.LogInformation("{Count} accounts, all balanced", result.AccountsChecked);
    }
    catch (LedgerCoreException ex) when (ex.StatusCode == 422)
    {
        // data carries the list of discrepancies
        logger.LogCritical("Balance drift detected: {Message}", ex.ApiMessage);
        await pagerDuty.TriggerAsync(ex.ApiMessage);
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 200,
      "message": "All balances verified.",
      "data": {
        "asOf": "2026-04-07T12:00:00Z",
        "accountsChecked": 412,
        "allMatch": true,
        "discrepancies": []
      }
    }
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json422">
    ```json
    {
      "code": 422,
      "message": "1 account(s) have balance discrepancies.",
      "data": {
        "asOf": "2026-04-07T12:00:00Z",
        "accountsChecked": 412,
        "allMatch": false,
        "discrepancies": [
          {
            "accountId": "acc_01HZ...",
            "accountCode": "CLIENT-42",
            "accountName": "Acme Retail",
            "storedLedgerBalance": 150000,
            "computedLedgerBalance": 149000,
            "difference": 1000
          }
        ]
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Response fields [#response-fields-1]

<TypeTable
  type="{
  asOf: { type: &#x22;datetime&#x22;, required: true, description: &#x22;When the check was performed&#x22; },
  accountsChecked: { type: &#x22;int&#x22;, required: true, description: &#x22;Total accounts examined&#x22; },
  allMatch: { type: &#x22;bool&#x22;, required: true, description: <><code>true</code> if every account reconciled</> },
  discrepancies: { type: &#x22;array&#x22;, required: true, description: &#x22;Accounts where stored ≠ computed&#x22; },
  &#x22;discrepancies[].storedLedgerBalance&#x22;: { type: &#x22;long&#x22;, required: true, description: <>Value in <code>account_balances</code></> },
  &#x22;discrepancies[].computedLedgerBalance&#x22;: { type: &#x22;long&#x22;, required: true, description: <>Value summed from <code>entry_lines</code></> },
  &#x22;discrepancies[].difference&#x22;: { type: &#x22;long&#x22;, required: true, description: <><code>stored − computed</code></> },
}"
/>

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

Running reconciliation on a schedule [#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.
