Opening Trial Balance

Use opening trial balance when an OPEX team — one that runs operating-expense accounting alongside trust accounting (see trust, operating, and combined ledgers) — needs correct account balances on the day before its GL start date. This endpoint seeds the final Combined trial balance by VRPlatform account; the API calculates the Operating opening effect by subtracting existing Trust activity before go-live.

The public endpoints are:

Get the opening trial balance — load editable accounts, calculated Trust values, Operating values, and lock state.
Replace the opening trial balance — replace the manual Combined balances.

Concepts

Combined, Trust, And Operating

Each row exposes three cent totals:

Field	Meaning
`combinedCentTotal`	The final Combined opening balance you submit.
`trustCentTotal`	Existing Trust ledger activity before the GL start date.
`operatingCentTotal`	Calculated as `combinedCentTotal - trustCentTotal`.

Only combinedCentTotal is submitted. Trust is calculated by the API, and Operating is projected into transaction-linked journal entries.

Internal Transaction

The API stores the source values on one internal opening-balance transaction:

type = journalBatch
uniqueRef = openingTrialBalance

This is intentionally not exposed through the public transaction create/update APIs. Use the General Ledger opening trial balance endpoints instead.

Assignment Row

The response includes an assignment row. It is calculated by the API so each column balances to zero. Clients must not submit the assignment account in rows[].

Workflow

Export a trial balance from the source system as of GL start date - 1.
Map source accounts to active VRPlatform Asset, Liability, and Equity accounts returned by GET /general-ledger/opening-trial-balance.
Submit the final Combined cent total per account.
Re-read the endpoint and review calculated Operating amounts.
Inspect opening-balance journal entries if needed.

This is an onboarding patch for opening balances, separate from detailed pre-go-live activity. Use Historical Journal Entries for detailed source journals.

Load Editable Rows

GET /general-ledger/opening-trial-balance

Example response shape:

{
  "glStartAt": "2025-01-01",
  "openingDate": "2024-12-31",
  "source": {
    "mode": "manual",
    "editable": true,
    "lastUpdatedAt": "2026-06-29"
  },
  "locked": false,
  "lockReasons": [],
  "rows": [
    {
      "accountId": "cash-account-uuid",
      "accountName": "Operating Cash",
      "classification": "asset",
      "type": "bank",
      "combinedCentTotal": 250000,
      "trustCentTotal": 150000,
      "operatingCentTotal": 100000,
      "editable": true
    }
  ],
  "assignment": {
    "accountId": "opening-balance-assignment-account-uuid",
    "accountName": "Opening Balance Equity",
    "combinedCentTotal": -250000,
    "trustCentTotal": -150000,
    "operatingCentTotal": -100000
  },
  "trustReversal": {
    "status": "not_created",
    "journalEntryIds": [],
    "lastRefreshedAt": null
  }
}

trustReversal.status is reserved for later automation. The current v1 contract returns not_created.

For teams without saved manual values, source.mode is none and source.lastUpdatedAt is null. After saving manual values, source.mode becomes manual.

Replace Balances

PUT /general-ledger/opening-trial-balance

{
  "rows": [
    {
      "accountId": "cash-account-uuid",
      "combinedCentTotal": 250000
    },
    {
      "accountId": "accounts-payable-account-uuid",
      "combinedCentTotal": -40000
    }
  ]
}

The request is a full replacement. Editable accounts omitted from rows[] are saved as zero.

Verify Journal Entries

Saving refreshes opening_trial_balance journal entries dated GL start date - 1. Use the journal entries report with openingBalanceType=openingTrialBalance to inspect them:

GET /reports/journal-entries?openingBalanceType=openingTrialBalance

Projected journal entries use:

type = opening_trial_balance
ledger = operating
party = manager
transactionId pointing at the internal journalBatch transaction

Zero Operating rows are skipped.

Guardrails

Updates are blocked when the opening date is books-closed, and when existing projected entries are attached to an owner statement.
Revenue accounts and non-equity Expense accounts are not editable in this endpoint.
Inactive, reference, and calculated assignment accounts are excluded.
Historical GL detail, CSV parsing, and external accounting sync are out of scope for this endpoint.

API Reference

GET /general-ledger/opening-trial-balance — Contract
PUT /general-ledger/opening-trial-balance — Contract
GET /reports/trial-balance — Contract
GET /reports/journal-entries — Contract

Opening Trial Balance

On this page