JavaScript · Track 5 · Tutorial 1 of 4

Send journal lines

Send the postings behind the month's figures - every journal, line by line - so any figure can be traced to the entries that made it.

You will needThe chart from Send your chart of accounts.
By the endSeptember's journals in BrizoConsol, every one balanced.

1What journal lines add

The trial balance gives each account's total for the month. Journal lines are the postings behind those totals - every debit and credit, with its date and description - so any figure can be traced to the entries that made it. Like invoices, they never change a figure.

2Write September's journals

Create journals.mjs. It describes six journals compactly and turns each posting into a line:

journals.mjs

// journals.mjs - sends September's journal lines.
import { call, companyId, show, written } from './brizo.mjs';

// Each journal: [journal id, date, description, [[account, side, amount, document], ...]]
const journals = [
    ['J-0901', '2026-09-05', 'Cash sales', [['1000', 'debit', 20000.00, null], ['4000', 'credit', 20000.00, null]]],
    ['J-0902', '2026-09-08', 'Invoice INV-1001', [['1200', 'debit', 10000.00, 'INV-1001'], ['4000', 'credit', 10000.00, 'INV-1001']]],
    ['J-0903', '2026-09-20', 'Payment from Harbour Trading', [['1000', 'debit', 5000.00, null], ['1200', 'credit', 5000.00, null]]],
    ['J-0904', '2026-09-03', 'Bill BILL-501', [['5000', 'debit', 8000.00, 'BILL-501'], ['2000', 'credit', 8000.00, 'BILL-501']]],
    ['J-0905', '2026-09-01', 'September rent', [['6000', 'debit', 2000.00, null], ['1000', 'credit', 2000.00, null]]],
    ['J-0906', '2026-09-25', 'Payment to Northwind', [['2000', 'debit', 3000.00, null], ['1000', 'credit', 3000.00, null]]],
];

const lines = [];
for (const [journalId, date, description, postings] of journals) {
    postings.forEach(([account, side, amount, document], n) => {
        const line = {
            journal_external_id: journalId,
            line_external_id: String(n + 1),
            date,
            account_code: account,
            side,
            amount_base: amount,
            description,
        };
        if (document !== null) {
            line.document_external_id = document;
        }
        lines.push(line);
    });
}

const request = written(await call('POST', `/organisations/${companyId}/transactions`, {
    declarations: {
        source_reference: 'my-ledger',
        period: '2026-09',
        value_basis: 'company_base',
        rate_direction: 'document_to_base',
        base_currency: 'SGD',
    },
    records: lines,
}));

await show('Journal lines', request);
console.log(`Lines an invoice or bill explains: ${request.suppressed}`);

const control = request.result.control_total;
if (!control.compared) {
    console.log('No trial balance from the API for this month to compare with.');
} else if (control.accounts.length === 0) {
    console.log('The lines add up to the trial balance, account by account.');
} else {
    for (const account of control.accounts) {
        console.log(`  ${account.account_code}: lines ${account.ledger}, trial balance ${account.trial_balance}`);
    }
}

Each line has the journal's ID, its own ID within the journal, a date, an account, a side - debit or credit - and amount_base, a positive amount in the company's currency.

Lines are identified by journal and line
A line's identity is its journal's ID and its own: sending it again updates it, never duplicates it.

3Send them

node journals.mjs

Check

Journal lines: request 99 - 12 created, 0 updated, 0 unchanged, 0 refused
Lines an invoice or bill explains: 4
The lines add up to the trial balance, account by account.

The last two lines are explained in the next two tutorials.

4Every journal must balance

BrizoConsol adds up each journal's debits and credits. If they differ, every line of that journal is refused with journal_does_not_balance, and the other journals are still stored. Send all of a journal's lines in the same request.

A journal is stored when it balances
Each journal is checked as a whole: its debits must equal its credits.

5One source per month

A company's ledger for a month comes from one source. If another source_reference already sent journal lines for September, your request is refused whole with month_held_by_another_source. Use one source name for one company's ledger.

6Sending more, or again

  • Lines can be sent in parts - a journal at a time, or a few days at a time. With the default mode, lines are added and updated, never removed.
  • "mode": "replace_all" removes every line this source holds from journals not in the request - in every month. Use it only to send the whole ledger in one go.
  • A company holds up to 1,000 journal lines a month.

Want more detail? See the documentation