What is an envelope?
The old cash-in-jars habit, applied to bank accounts. A service business that collects GST and pays contractors has two sums it must not spend: the GST it is holding for the ATO, and the money it will owe contractors for work already scheduled. Keeping each in its own savings account is common practice. What is uncommon is knowing, on any given Tuesday, whether the balance in there is enough.
Biloh answers that with get_envelope_targets: for each envelope, what should
be there, what is, and the gap.
How is each target computed?
Tax set-aside. The net GST position for the open BAS quarter to date (1A
less 1B, from the same library the BAS worksheet reads) plus an income-tax
provision: finance.envelopes.income_tax_provision_pct of net cash profit for
the financial year to date. That percentage defaults to zero, and the response
carries provision_unset until you set it. The platform never guesses a tax
rate; that number is yours and your accountant's.
Contractor buffer. Open contractor payables (work released but not yet
paid) plus the projected cost of scheduled visits over the next
finance.envelopes.buffer_horizon_weeks (default six), each visit priced at
its effective contractor rate. Because the schedule is the same engine that
spawns the jobs, the projection is the real forward book, not an average.
How are actuals measured?
By the chained bank balance of the account registered for that purpose, never
a figure someone typed. Register the accounts once with create_bank_account,
giving each its purpose (tax_set_aside, contractor_buffer, operating).
An envelope with no account registered for its purpose still shows its target
and reports no_account_registered, so the gap is named rather than hidden.
The tolerance before the attention digest names a shortfall is
finance.envelopes.digest_tolerance_cents (default $50).
What does Biloh do about the gap?
Nothing at the bank. get_envelope_targets advises; it never moves money. The
weekly accountant summary carries a sweep card: "move $X to the tax set-aside,
$Y to the contractor buffer". You make the transfers in your banking app.
When both accounts' statements are next imported, get_reconciliation_suggestions
offers the debit in the everyday account and the equal credit in the savings
account as a possible_transfer, and match_transfer_pair confirms them as
the two halves of one movement of your own money. Both lines move to a
transfer state and reach no report, while remaining real lines in both
accounts' balance chains. The pair is reversible with unmatch_transfer_pair.
The two halves must be equal, in different registered accounts, and land
within finance.bankfeed.transfer_window_days of each other (default three).
If a fee was taken so the amounts differ, pair nothing; code the fee
separately.
Why does this matter for the close?
Because an envelope shortfall is the earliest warning that a BAS will hurt. A
business that sees "tax set-aside is $1,200 short of target" in week four of
the quarter has time to fix it. One that discovers it on lodgement day does
not. The envelope report sits at the top of get_accountant_summary for that
reason.