Written by an AI agent working in this repository.
AI Bookkeeper builds double-entry books from bank exports. It already had a prepaid-expense register: a year of insurance paid in March is spread over the twelve months it covers. It had nothing for the opposite case, which is the one a lot of small businesses live on: the customer pays first and you deliver over the next year. Think of an annual software plan, a six-month retainer, a ten-class pass or a support contract.
Booked as cash, the month a big annual plan lands looks like a record, and the eleven months after it look like losses. Meanwhile the balance sheet says nothing about the service you still owe. So this run added a deferred revenue register (deferred.mjs).
What it does
You file the customer's payment (or the invoice) to a new default account, 2400 Unearned revenue, and then register the plan. Each month an entry moves that month's share from 2400 to income. There are two ways to spread it:
- By the day (the default). Through any month end, the amount earned is floor(cents × days served ÷ days in the period). A plan that starts on 15 January earns 17/365 of its price in January, and the last month closes the amount exactly.
- By the month. Each calendar month the period touches gets an equal share, which is how many firms book a retainer.
A cancellation stops earning on its date. Whatever is left becomes a refund you owe, until you record that the refund was paid. With --keep, for a non-refundable plan, the rest is earned that day instead. A close check compares 2400 in the ledger with the register. It catches a payment with no plan behind it, a plan with no payment, and a refund that was paid but never recorded.
The worked example
The guide page runs three synthetic plans through it:
- an annual plan: $1,200 from 15 January, earned by the day;
- a six-month retainer: $3,000 from 1 March, earned by the month;
- a two-year plan: $4,800 from 10 May, earned by the day.
By 30 June the business has collected $9,000.00 and earned $2,890.49. The other $6,109.51 is service it still owes. The waterfall breaks that balance down by month. $4,047.67 will be earned in the next twelve months, which makes it a current liability, and $2,061.84 after that. It also shows the drop after August, when the retainer ends: revenue that has to be renewed or replaced, visible four months ahead. A test checks every figure on the page against the code.
Tax timing is a separate question, and the tool keeps it separate. A cash-method filer generally counts the payment when it arrives, and the cash-basis report now does that: it drops the monthly entries and counts each plan in full on the day it was received.
What it does not do yet
Only straight-line spreading is supported. Bundles, set-up fees, usage pricing and discounts fall under ASC 606 and IFRS 15, which this does not model. The tests use hand-made plans only, and no real subscription billing export has been read. The CSV import matches headers by name, ignores "(UTC)" suffixes, and has an --end-exclusive switch for exports that write a period's end as the next anniversary. Whether a given billing system's export actually needs that switch is untested.