Supply WeaveDocumentation
Product guidesAccounting
Supply Weave
DocsAccountingOpening-Balance Import Guide

Opening-Balance Import Guide

Purpose And Responsibility

This guide explains how an authenticated ADMIN loads an agreed accounting cutover into Supply Weave. The application preserves source rows, validates the normalized content, prevents duplicate posting, writes a balanced opening journal, and records compact audit evidence. It does not determine the correct opening balances.

The business and its CA are responsible for the approved cutover date, chart-of- accounts mapping, brought-forward amounts, retained earnings, mid-year Revenue and Expense balances, tax and VAT positions, depreciation, provisions, and supporting workpapers. Obtain CA-approved, balanced source data before posting.

Prerequisites

  1. Configure the company accounting settings and generate the fiscal year that contains the opening date.
  2. Confirm the opening date belongs to an OPEN accounting period.
  3. Complete the chart of accounts. Every imported account code must resolve to an active leaf account; account code is authoritative.
  4. Agree the opening-balance cutover date. The first successful post freezes accountingSettings.openingBalanceCutoverDate; a replacement must use that same date.
  5. Review Accounting Readiness and resolve blockers applicable to opening-balance posting. Global readiness is diagnostic; posting recalculates its contextual blocker set inside the transaction.
  6. Retain the approved source trial balance and mapping workpaper outside the application.

CSV Contract

Download the template from /accounting/opening-balances/create rather than constructing a differently named file. The required header is:

account_code,account_name,debit,credit,memo
  • account_code is required and authoritative for account lookup.
  • account_name is informational and does not override the configured account.
  • Enter a positive amount on exactly one of debit or credit for each row.
  • Amounts use no more than four decimal places. Do not use negative amounts.
  • Do not repeat an account code in the same import.
  • Total debit must equal total credit exactly.
  • The maximum upload size is 5 MB.
  • Malformed values and parser errors are preserved for review; raw values are never posted directly.

Create And Validate

  1. Open /accounting/opening-balances and select Create Opening Balance.
  2. Choose Manual rows or CSV upload, set the agreed opening date, and create the draft. Both methods feed the same draft and validation model.
  3. On the detail screen, review every row and save corrections before validating. A row replacement resets the import to DRAFT.
  4. Select Validate. The server resolves accounts, checks active-leaf status, duplicate codes, one-sided positive fixed4 amounts, exact balance, date and cutover rules, and duplicate content.
  5. If status is INVALID, correct every row-level and import-level error, save, and validate again. Invalid imports never affect the ledger.
  6. When status is VALIDATED, compare the normalized preview, row count, total debit, total credit, and content hash with the approved source and mapping.

The content hash is a versioned SHA-256 value over opening date, BDT, and sorted normalized posting rows. Source filename, input order, account name, and import method do not affect it. This allows manual and CSV sources with the same normalized content to identify the same proposed posting.

Post

Posting is consequential and makes the rows immutable.

  1. Record the validated content hash in the approval evidence.
  2. Select Post Opening Balances and verify the confirmation displays the same hash.
  3. Confirm posting once. The API submits expectedContentHash and recomputes rows, totals, readiness blockers, and hash while holding the accounting controls.
  4. If the content changed, posting fails with CONTENT_HASH_MISMATCH; return to the draft, revalidate, and obtain approval for the new hash. Do not bypass the mismatch.
  5. Confirm status is POSTED, total debit equals total credit, and the linked OPENING_BALANCE_IMPORT journal contains one line per accepted row.
  6. Review the opening balances in the Trial Balance, relevant General Ledgers, and Statement of Financial Position. Investigate every reconciliation warning.

Only one import may currently be POSTED. A posted content hash remains globally reserved even after reversal. Retrying the same posted import with the same hash is idempotent and returns its existing journal rather than creating another posting.

Reverse And Replace

Do not edit a posted import or delete its journal.

  1. Obtain approval and a specific nonblank reversal reason.
  2. Confirm the current date belongs to an open accounting period; reversal posts in that current period, not the original opening period.
  3. Select Reverse. The application preserves and marks the original journal reversed and creates an OPENING_BALANCE_IMPORT_REVERSAL journal with swapped debit and credit lines.
  4. Verify status REVERSED, both journal links, reversal reason, actor, timestamp, reports, and Audit Logs.
  5. Create a replacement draft using the frozen cutover date. Corrected content must produce a different hash because the original posted hash cannot be reused.
  6. Repeat validation, approval, posting, report reconciliation, and evidence retention.

Audit And Evidence

Opening-balance create/upload, row replacement (PUT), validation, posting, idempotent retries, and reversal use authoritative transactional audit events. The compact before/after summary contains the import ID, opening date, method, status, source filename, validation and posted hashes, row count, total debit, total credit, error count, and original/reversal journal links. Stable action metadata records filename, the authoritative content hash, counts, totals, error count, and resulting journal ID, plus applicable idempotency or reversal-reason context.

Complete rows, rawData, and raw CSV contents are excluded from audit payloads. The import record remains the source of truth for the original filename and content hashes. After the transaction commits successfully, the service marks the request audit as handled so middleware does not add a duplicate success event. Failed attempts remain eligible for request-level failure auditing.

Retain:

  • CA-approved source trial balance and account-mapping workpaper.
  • Opening date, source filename where applicable, and import ID.
  • Validated and posted content hashes.
  • Row count, exact debit/credit totals, and resolved validation errors.
  • Approval evidence and operator identity.
  • Original and reversal journal IDs where applicable.
  • Audit Log records and reconciled report exports.

See docs/operator-period-close-checklist.md before closing the opening period and docs/ca-handover-and-export-guide.md when preparing the accountant handover.