Historical Journal Entries

Use historical journal entry import when a team needs pre-go-live general ledger detail in VRPlatform, but that detail should not affect live trust or operating balances after the GL start date.

POST /general-ledger/historical accepts already-mapped source journals. The API does not parse QuickBooks, Xero, CSV, or PDF files. Your client extracts the source data, maps each source account to a VRPlatform account, and posts balanced source journal entries.

When To Use This

Use this endpoint for detailed historical GL reporting before go-live:

old profit and loss activity
old balance sheet movement
source accounting journals that users may want to inspect later
backfilled GL detail that should stay separate from opening balances

Do not use it to seed opening balances. Use Opening Trial Balance for the final Combined balances as of GL start date - 1.

Concepts

Historical Ledger

Imported rows produce journal entries with:

ledger = historical
status = inactive
type = historical_general_ledger
party = manager

Historical ledger rows are for pre-go-live reporting detail. They do not post to the active trust or operating ledgers and do not change post-go-live GL balances.

One Source Journal Becomes One Batch

Each entries[] item represents one balanced source journal entry. The API stores it as one internal journalBatch transaction. The entry date belongs on that transaction, not on each individual line.

The internal transaction unique ref is derived from your stable import and entry keys:

historical-general-ledger:{importUniqueRef}:{entryUniqueRef}

Idempotency

uniqueRef is the import idempotency key. Re-posting the same import uniqueRef replaces all transactions owned by that import: matching entry refs are updated, new ones are created, and old refs omitted from the new payload are deleted.

This lets import tooling safely rerun after users fix mappings or source data.

Prerequisites

The team has a GL start date.
Every source journal date is before the GL start date.
The target VRPlatform accounts already exist.
Each source journal entry balances to zero.
Each source journal entry has at least two non-zero lines.
Optional listingId, reservationId, and contactId values already exist in the team.

Import Journals

POST /general-ledger/historical

{
  "uniqueRef": "qbo-history:2024",
  "description": "QBO historical GL import",
  "currency": "usd",
  "entries": [
    {
      "uniqueRef": "journal-2024-12-31-001",
      "date": "2024-12-31",
      "description": "December rent accrual",
      "lines": [
        {
          "uniqueRef": "cash",
          "accountId": "cash-account-uuid",
          "centTotal": 125000,
          "description": "Cash"
        },
        {
          "uniqueRef": "rent",
          "accountId": "rent-income-account-uuid",
          "centTotal": -125000,
          "description": "Rental income"
        }
      ]
    }
  ]
}

Amounts are signed cents. The lines inside each entry must sum to zero. Use the same sign convention as journal entries: debit-positive, credit-negative.

Example response:

{
  "uniqueRef": "qbo-history:2024",
  "replaced": false,
  "transactionCount": 1,
  "journalEntryCount": 2,
  "transactionIds": ["transaction-uuid"]
}

Verify The Import

Use the journal entries report with ledger=historical to inspect imported rows:

GET /reports/journal-entries?ledger=historical

Imported rows should show type = historical_general_ledger and the original entry date as txnAt.

Guardrails

Entry dates on or after the team GL start date are rejected.
Unbalanced source entries are rejected before any transaction is written.
Import uniqueRef values may not use the reserved historical-general-ledger: prefix.
Public transaction create, update, and batch endpoints do not accept journalBatch; this endpoint owns the internal transaction shape.
Books-closed dates are ignored for this import because the data is pre-go-live history on the historical ledger.