Skip to main content

Preview Opening Balances from Provider

GET 
/api/ledger/opening-balance/provider-preview

Reads the selected connection's Trial Balance "as at" the snapshot date and proposes opening-balance lines mapped onto SKU's chart of accounts. Works for both QuickBooks Online and Xero connections — the trial balance is fetched from whichever provider the connection belongs to. Read-only — nothing is persisted; the frontend uses the result to seed the opening-balance draft editor, which the user then reviews and applies.

Authorization

Any valid API token can call this endpoint — no specific scope required. Manage tokens.

Mapping rules:

  • Each provider account is matched to a SKU nominal code by code.
  • The signed provider balance (debit-positive) is split into a direction (debit when ≥ 0, else credit) and a positive amount.
  • Near-zero balances (|balance| < 0.005) are skipped.
  • The inventory-control account is excluded (returned as skipped_inventory) — SKU derives that opening line from its own valuation, so importing the provider figure would double-count it.
  • Provider accounts with no code, or whose code matches no nominal code, are returned in unmatched so the user can map them and re-fetch.

Errors: returns 422 with a friendly message when the connection's provider cannot produce a trial balance report, and 404 when connection_id is not a supported accounting connection.

Authentication: Requires Bearer token. (Read-only route — no extra permission middleware; the mutating apply/upsert routes enforce accounting.manage_settings.)

Query parameters:

  • connection_id (integer, required) — the integration instance to read from.
  • as_of (date Y-m-d, optional) — trial-balance snapshot date; defaults to today.

Each lines[] and unmatched[] item also carries account metadata from the provider's chart of accounts: account_class (normalized bucket: Asset, Liability, Equity, Revenue, or Expense; null when unknown), account_type (the provider's own finer account type label, e.g. "Fixed Asset"), and mirror_account_id (the id of the provider account record in SKU, for linking to its detail view; null when the account is not mirrored locally).

Request​

Responses​

OK

Response Headers
    Content-Type