Step 1: close the quarter
A BAS read from an open quarter is a forecast. Close the three months and the quarter first; see close a month and a quarter. The worksheet can be read at any time, and it will agree with the closed snapshot because both read the same library.
Step 2: read the worksheet
"What do I owe the ATO for July to September?"
get_bas_worksheet returns the quarter's figures mapped to the ATO's labels,
in the order the form asks for them:
| Field | What it is |
|---|---|
totalSalesG1 | Total sales, GST-inclusive |
gstOnSales1A | GST on sales |
gstOnPurchases1B | GST on purchases, the claimable figure |
netGstCents | 1A minus 1B, signed; positive is payable, negative is a refund due |
paygInstalment | isSet: false and cents: null until you record the ATO's figure |
exceptions | Every purchase whose GST is held out of 1B, as "claimable once paper lands" |
Lodging in ATO Online services is then copy-across, field by field. Read the exceptions before you lodge: each is a purchase whose GST would return to 1B if its tax invoice were attached. If the paper exists, attach it now and read the worksheet again. See cash-basis BAS.
If the ATO has issued a PAYG instalment, record it with update_setting on
finance.bas.payg_instalment_cents. Until then the slot is explicitly not
set rather than a zero somebody might copy onto a form.
Step 3: generate the pack
"Generate the pack for the July to September quarter."
generate_period_pack composes one ZIP with the folder tree the accountant
expects (FY2027/Q1 Jul-Sep/2026-07 July/…). Each level carries its own
drawer:
- A month pack: the receipts ledger, bank coverage per account, and the evidence index.
- A quarter pack: the Sales and GST and Purchases and GST reports as
spreadsheet and print-ready PDF, the BAS worksheet, the GST workings, the
exceptions list, the evidence bundle (the substantiating documents
themselves, up to
finance.pack.evidence_bundle_max_mb), the cash P&L, and an empty slot for the ATO lodgement receipt. - A financial-year pack: an
Annual/folder with the P&L, the TPAR, the depreciation schedule, the balance sheet, the annual GST summary (the four quarters' worksheets side by side, section-summed) and income by customer, each as spreadsheet and PDF.
Every pack opens with a cover page and a README composed from its own manifest, and embeds the latest child packs byte-identical (a missing child gets a "not yet generated" note). Every figure is a read, never a recompute: the pack and the live report cannot disagree because there is only one of them.
Generation is idempotent while nothing moves; a second call on an unchanged period returns the same pack. If the period was reopened and a figure moved, the next call mints version plus one and records that it supersedes the previous, which stays readable forever.
get_period_pack reads a pack back: its manifest (every file with a sha256,
its size, its source library and as-of stamp), the composed figures, and a
short-lived signed download link.
Step 4: the year-end reports
For the financial year, the same tools answer the accountant's questions directly:
get_profit_and_loss: the cash P&L, every figure ex-GST, over your reporting categories, with the prior period beside every line.get_balance_sheet: assets against liabilities as at any date, with equity as the residual and the GST position signed honestly as a liability or an asset. It states what it does not hold.get_tpar_report: the Taxable Payments Annual Report, one row per subcontractor with ABN, address on file, total paid GST-inclusive and the GST component, produced from the payment ledger. Due 28 August.get_depreciation_schedule: opening written-down value, additions, depreciation, disposals and closing value per asset, tying across years by construction.get_aged_payables: what is owed to contractors by age bucket.
Step 5: keep the calendar
"When is the BAS due, and is anything overdue?"
list_obligations is the compliance calendar. On a business's first read it
seeds the financial year's four BAS quarters, four super quarters and the TPAR
with the correct Australian due dates; reading again mints nothing. Each row
says days_until_due, is_due (inside finance.obligations.lead_days, when
it starts appearing in your attention digest) and is_overdue.
Add the renewals the platform cannot know about, such as vehicle registration
or public-liability insurance, with upsert_obligation. An annual cadence
means lodging this one mints next year's, so a renewal is entered once and
chases itself.
When you lodge, mark_obligation_lodged records it and requires the receipt:
receipt_document_id must name a lodgement receipt already in the evidence
layer. A lodgement without proof is refused, so the pack's empty slot for the
ATO receipt is filled the same way every quarter.
The weekly read
get_accountant_summary is all of the above at a glance: envelope targets
against actuals with the sweep card, period status per bank account and the
close ladder, the exceptions block (untriaged lines, unmatched credits and
debits, missing evidence, unpaired shoebox items, stale feeds, open and
overdue obligations, and any contradictions), and the cards awaiting you with
their ages. Every block names the library that produced it.