By the end of this chapter you can

• Say what the module does and what stays in the accounting system, tax engine and payment provider.
• Name the six sources an invoice can come from and the billing terms an account carries.
• Explain why a sent invoice is never edited and why numbering has no gaps.

What this module is for

Quotes, orders and invoicing turns accepted quotes and shipped or completed work into correct invoices: billing terms, tax by the rate in force, credit notes, payment application and statements. Every invoice is then posted once to the accounting system through a signed posting contract. The module stops there on purpose. The general ledger, payables and financial statements stay in the accounting system; tax calculation engines, subscription revenue schedules and card or bank processing stay with the products built for them.

• In: billing accounts and terms, invoices from six sources, tax lines, credit notes, payment application, statements and reminders, and one idempotent posting per document.
• Out: the general ledger, payables and financial statements; tax engines; revenue schedules; card and bank processing. These are integrated, not rebuilt.
• Later tiers: remittance matching from bank statements and e-invoicing export are extra capabilities, not part of the first version.
• Not built in the practice sessions: milestone and time-and-materials invoices, refunds, and the consumers for the shipped, completed and milestone-accepted events. There the billing clerk starts a draft from a shipped order or finished work by hand; only the quote-accepted consumer is built.

Billing accounts and terms

A billing account says who is billed and on what terms. It points to the customer as a party in the core tables, may link softly to the sales account, and carries a currency, payment terms, a tax-exempt flag with the certificate reference and its expiry date, an optional credit limit, and a status of active, on_hold or closed. The due date on an invoice is worked out from the terms when it is issued.

An exemption certificate has an expiry date for a reason: the day after it lapses, the account is taxable again unless a new certificate is on file. The invoice screen should warn before that day, not after.

Six sources, one invoice table

A hard foreign key goes only to the shared core tables and to this module's own tables. Links to the sales order, work order, project and quote are soft: the id is stored, but the other module can change independently. A manual invoice has no source document, so it carries one control instead: above a set amount it needs a second person's approval, held in core_approval, and the invoice keeps the approval id.

Money, currency and numbers

All money is held as whole numbers of the currency's smallest unit (cents for the dollar), never as fractions. The currency code and its minor unit come from ISO 4217: most currencies have two decimal places, some have none and some have three, so the module stores the code beside every amount ^[4]. A tax rate is a number, but an amount of tax is always rounded once, by a rule written down, into whole cents.

Invoice numbers are gapless within a series. A draft carries a temporary number so it can be saved, and the real number is drawn from the number sequence only at the moment of issue, inside the same database transaction that issues the invoice. If that transaction fails, no number is used up. Skipped numbers are the first thing an auditor looks for.

An issued invoice is never edited

The reason is plain: the customer, the accounting system and the tax authority may all hold a copy of what was sent. Records of this kind are kept for a period set by the rules that apply to the business, and guidance such as the IRS's record-keeping publication describes what to keep ^[2]. Keep the original exactly as issued.

The ten tables

Every column of the ten tables

Copy these tables into your own docs/bill-tables.md; your agent builds the migration from them. Types: uuid, text, boolean, date, integer and timestamptz (a date and time with its time zone) are plain; money is a bigint holding whole cents; quantity is numeric(18,4); a rate is numeric(9,6). Required means not null. An arrow means a hard foreign key (a column whose value must match the id of a row in that table); a soft link is a plain uuid with a comment and no constraint, because the module that owns the row may not be installed. Every table also has the standard columns: id, tenant_id, created_at, created_by, updated_at, updated_by, row_version, archived_at and ext.

bill_billing_account

bill_invoice

bill_invoice_line

bill_tax_rate

bill_credit_note

bill_payment

bill_payment_application

bill_dunning_step

bill_dunning_event

bill_posting

Outside this module, the invoice also follows the shape of an electronic invoice: the EN 16931 semantic model defines what an invoice must be able to say, and Peppol BIS Billing 3.0 applies it to a network ^[1][3]. The tables are built so an export can be produced later, without a second data model.

Exercise · Sort your last twenty invoices30 minutes

You need: Your invoicing tool (or spreadsheet), a private folder outside the repository, and a copy of the table above

Customer names and amounts are private business data. Work in your own tool, keep any export in a private folder and never paste it into a chat or a prompt.

1. 1. List your twenty most recent issued invoices with number, date, customer and total.
2. 2. Beside each, write the source_type it would have: sales_order, shipment, service_work_order, project_milestone, time_and_materials or manual.
3. 3. Beside each, write the payment term the customer was on, using the terms in the table above.
4. 4. Mark every invoice that was edited after it was sent, if your tool shows this, and every invoice later corrected by a credit note.
5. 5. Check the number series for gaps: write down each missing number and what happened to it.
6. 6. Count how many invoices needed a second person's approval and who gave it.
7. 7. Write three sentences: which source is most common, how many were edited or credited, and whether the numbers have gaps.

Outcome: A one-page inventory of twenty invoices by source, terms, edits and gaps. It tells you which parts of the module you will use most, and where today's process breaks the never-edit rule.

References

1. European Commission: EN 16931, the European standard on electronic invoicing. https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/Obtaining+a+copy+of+the+European+standard+on+eInvoicing
2. IRS Publication 583: Starting a Business and Keeping Records. https://www.irs.gov/publications/p583
3. Peppol BIS Billing 3.0 (OpenPeppol). https://docs.peppol.eu/poacc/billing/3.0/
4. ISO 4217 currency codes. https://www.iso.org/iso-4217-currency-codes.html

By the end of this chapter you can

• Choose the tax rate for an invoice from a dated rate table and keep it fixed afterwards.
• Correct an invoice with a credit note and a reissue, and apply a payment to one or many invoices.
• Describe a reminder schedule that stops when the invoice is paid or disputed.

Tax lines by ship-to and date

Each invoice line carries a tax code and a tax amount. The rate comes from one of two places: an integrated tax engine (best when the rules are complex, because the engine owns them) or, for simple cases, a dated rate table in bill_tax_rate. Either way, the rate depends on where the goods or service go, the ship-to, and on the date the rules say applies. Which date counts is a tax-rules question for the business's accountant; the module stores one date on the invoice and uses it for every line.

The lookup is a date test: the row where valid_from is on or before the date and valid_to is empty or on or after it. A rate change is a new row with a new valid_from, never an edit to the old one, in the same way a price book change is a new version.

A worked example in whole cents

A two-line invoice: 4 units at 2,500 cents and one service at 12,500 cents, so a subtotal of 22,500. At the example rate of 6.00% the lines carry tax of 600 and 750, a tax_total of 1,350 and a total of 23,850. At 6.50% the same lines carry 650 and 813 (812.5 rounded half up), a tax_total of 1,463 and a total of 23,963. Write the rounding rule down (per line or on the total, and which way a half cent goes), apply it everywhere, and test it, because it will be questioned the first time two invoices differ by one cent.

The rates in this chapter (6.00% and 6.50%) are examples for reading the figures. The practice seed in the sessions uses other made-up rates (5% and 7%), so its hand-counted totals differ from these; neither is a real jurisdiction's rate.

An exempt customer is handled by the account, not by the line: when tax_exempt is set and the certificate has not expired, lines carry zero tax and the certificate reference, so the audit trail shows why.

Credit notes: the only correction

A credit note credits an invoice in full or in part, with a reason code from the shared reason-code table, an amount and a tax amount held separately, and a status of draft, approved, issued or applied. A reissued invoice is linked back by reissued_invoice_id. Credit notes use the same gapless numbering as invoices, in their own series, and the same approval rule above a limit.

Electronic invoice formats treat a credit note as a document type of its own, with the same structure as an invoice and a reference to the invoice it corrects. UBL 2.1, the OASIS standard also published as ISO/IEC 19845, defines both an Invoice and a CreditNote ^[1]. Modelling it this way now means the tables are built so an export can be produced later, with no workaround.

Payments and their application

A payment records money received: the account, the date, the amount and currency (in the currency's minor unit ^[2]), the method (card, ach, wire, check, cash or other), the reference the customer gave, and the payment provider's reference. The module never stores a card number or bank account number; the payment provider holds them. A payment is then applied to invoices in bill_payment_application, one row for each invoice it pays.

• Partial payment: less than the invoice total. The status becomes partially_paid and balance_due falls by the amount applied.
• Payment across invoices: one payment applied to several invoices, one application row each.
• Overpayment: the excess stays in unapplied_amount as unapplied cash. It can be applied to a later invoice, or handed back by the payment provider outside this module (refunds are not built here); the payment itself is never edited to hide it.
• The invariant: a payment's amount always equals its applications plus its unapplied_amount. A test can check this for every row.

Matching a bank statement line to an open invoice is a later capability. Bank statement and payment notification formats are defined by ISO 20022 (camt.053 for statements, camt.054 for notifications) ^[3]; the reference and provider_ref columns hold what a later remittance-matching step can use.

Statements and reminders

A statement lists a customer's open invoices, credits and payments at a date. Reminders are a schedule, not a habit: each bill_dunning_step says how many days overdue, which channel (email, letter or call_task), which template, and whether to stop on dispute. Each reminder that fires, or is skipped, is recorded in bill_dunning_event with an outcome of sent, skipped_dispute, skipped_paid or failed. A paid invoice simply leaves the ladder, so nothing more is recorded for it; skipped_paid is recorded only when a reminder was queued before the payment arrived and is then not sent.

Exercise · Price one invoice by its date30 minutes

You need: One real issued invoice from your tool, a calculator, and your accountant's written statement of the tax rate and the date that applies

Use a single invoice with at least two lines. Do not guess a tax rate: take it from your accountant, your tax authority's page or your tax engine. Keep the invoice in a private folder.

1. 1. Write down the invoice's ship-to, its issue date and the date your accountant says the tax rate follows.
2. 2. Write the rate in force on that date as one bill_tax_rate row: jurisdiction, tax_code, rate, valid_from and valid_to.
3. 3. Convert each line to whole cents and compute each line's tax with a written rounding rule.
4. 4. Add the lines to a subtotal, tax_total and total, and compare them with the invoice your tool issued.
5. 5. Write the rate row you would add if the rate changed next month, and state which invoices it must not change.
6. 6. If the customer is exempt, write the certificate reference and expiry date you would store and what the invoice should do the day after it lapses.

Outcome: A short table showing one invoice repriced in whole cents from a dated rate row, with the rounding rule, any difference from the issued invoice explained, and the rule for the next rate change.

References

1. OASIS: Universal Business Language (UBL) Version 2.1. https://docs.oasis-open.org/ubl/UBL-2.1.html
2. ISO 4217 currency codes. https://www.iso.org/iso-4217-currency-codes.html
3. ISO 20022: financial messaging standard. https://www.iso20022.org/

By the end of this chapter you can

• Explain how an idempotency key stops a retry from posting twice.
• Name the roles and screens that touch money and the rule each follows.
• Reconcile the platform to the accounting system at cut-over and prove the module with its four KPIs.

The posting contract

Every invoice, credit note and payment is posted once to the accounting system. The contract is simple: the module writes a bill_posting row for the document with a unique idempotency key, a posting service sends the document and the key, and the accounting system answers with an acknowledgement and its own reference. The module does not keep a ledger; it keeps proof that each document reached the ledger exactly once.

The contract is signed: the adapter signs each request with a secret it shares only with the accounting side, kept in the host's environment settings, so the receiver can check who sent it and that nothing changed on the way. The database allows one posting row per document, whatever its key, so an opening posting loaded at cut-over is found and reused when that document is later paid or applied.

An idempotent retry

A network can fail after the accounting system has done the work but before the reply arrives. The sender cannot tell this from a failure before the work, so it must be safe to send again. An operation is idempotent when doing it twice has the same effect as doing it once. Payment and billing APIs achieve this by asking the caller to attach a key, and by returning the earlier result when the same key comes back. Build the key from the document, such as its type and id, so every attempt produces the same one.

Where the accounting system does not honour keys itself, the adapter does the same work: it checks its own bill_posting row and looks the document up in the accounting system by the key, stored in the document's reference field, before it creates anything.

A failed posting is shown to a person with its last_error, can be retried from the postings screen, and publishes bill.posting.failed so another module or an alert can react. A retry never edits the document; it only repeats the posting.

Who may do what

Nobody deletes anywhere. Two rules are enforced twice, by a restrictive rule in the database and by a test: the approver cannot approve what they created, and only the posting service updates a posting. The screens follow the roles: invoice, payment and setup screens for the billing clerk (setup is where accounts, dated tax rates and reminder steps are kept), an approvals queue for the approver, and a board for open balance, ageing and the four KPIs.

Measuring the module

Take each number once from the old tool before you build, and again from the new one after. For example, with receivables of 150,000 and credit sales of 450,000 over a 90-day period, DSO is 150,000 ÷ 450,000 × 90 = 30 days. The figures are illustrative; use your own.

Cut-over without losing a cent

Migration is a small, careful import, not a history transfer. Export the open invoices, customers and unapplied payments from the old tool; load each opening balance as one posting, in the same way as any other document, with a key that starts opening: so it can never clash with a live one; and issue new invoices from the cut-over date while the old system keeps its history. The importer role is created in Session 3, used only for the rehearsal and the cut-over run, and removed afterwards.

Two further capabilities are built on the same tables. E-invoicing export produces an EN 16931 or UBL 2.1 document for customers or mandates that require it ^[2]. Remittance matching proposes which open invoices a bank statement line pays. Neither changes the rules above.

Records are kept as long as the rules that apply to the business require; the IRS's record-keeping guide lists what to retain ^[1]. Because issued invoices and postings are never deleted, retention is a matter of archiving, not of rebuilding.

Exercise · Break the retry on purpose30 minutes

You need: Your rehearsal database (never the live one), your AI coding agent, and the journal file or test double that stands in for the accounting system

Do this in the rehearsal environment you built in the sessions. The aim is to see the guarantee hold, then to see what it looks like when it does not.

1. 1. Pick one issued invoice in the rehearsal and note its bill_posting row: status, attempts and idempotency_key.
2. 2. Make the stand-in accounting system answer after it records the entry but before the reply returns, so the service sees a timeout.
3. 3. Run the retry and count the ledger entries in the stand-in. Write the number.
4. 4. Change the key to include the time of the attempt, run it again, and count the entries. Write the number and change it back.
5. 5. Try to update the issued invoice's total from a script. Write what the database says.
6. 6. Insert a second bill_posting row with the same idempotency_key and write what the database says.
7. 7. Write the three results in a table beside the three tests that define done.

Outcome: Three observed results: one ledger entry after a retry with the same key, two entries with a time-based key, and refusals for the invoice update and the duplicate key. Together they show the guarantees hold and what each one prevents.

References

1. IRS Publication 583: Starting a Business and Keeping Records. https://www.irs.gov/publications/p583
2. European Commission: EN 16931, the European standard on electronic invoicing. https://ec.europa.eu/digital-building-blocks/sites/display/DIGITAL/Obtaining+a+copy+of+the+European+standard+on+eInvoicing

Choose one answer for each question, then submit. You will see the right answer and why for every question.

1. What is the only way to correct an issued invoice?

AEdit the line and send it again with the same numberBDelete it and reuse its numberCIssue a credit note and, if needed, a reissued invoiceDChange its status back to draft

2. A posting times out and the service retries. What stops the accounting system recording it twice?

AThe same idempotency key on every attempt, checked before anything is postedBA fresh key on each attemptCWaiting an hour between attemptsDA person deleting the extra entry afterwards

3. A tax rate changes on 1 July. Which rate does an invoice issued on 15 March use when it is reopened in August?

AThe newest row in bill_tax_rateBThe rate on the day it is openedCThe average of the two ratesDThe rate in force on its own date, stored when it was issued and never recalculated

4. A payment of 30,000 cents is applied 23,850 to one invoice and 4,000 to another. What is its unapplied_amount?

A0B2,150C27,850D30,000

5. Which of these stays outside the module and is integrated instead?

ACredit notesBThe general ledger and financial statementsCPayment recordingDCustomer statements

6. Why does a draft invoice carry a temporary number?

ACustomers prefer shorter numbersBTax law forbids numbering draftsCDrafts are never savedDThe real number is drawn only at issue, so an abandoned draft leaves no gap in the series

7. Where are card and bank account details held?

ABy the payment provider; the module never stores themBIn bill_payment.referenceCIn the billing account recordDIn the invoice's ext column

8. A reminder falls due on an invoice marked disputed, and the step has stop_on_dispute true. What is recorded in bill_dunning_event?

AsentBfailedCskipped_disputeDskipped_paid

9. Which KPI is invoices issued without a later credit note divided by invoices issued?

ADSOBTime to invoiceCPosting successDInvoice accuracy

10. At cut-over the platform's open balance differs from the accounting system's receivables. What is the correct action?

AStop, explain the difference account by account, and continue only at 0 centsBBook the difference to an adjustment accountCGo live and correct it next monthDUse the larger of the two numbers

11. Which standard defines the semantic model of an electronic invoice?

AISO 4217BISO 20022 camt.053CEN 16931DIRS Publication 583

12. Why is money held as whole numbers of cents?

AWhole numbers are shorter to typeBNo fractions can creep in, so amounts add exactlyCBanks require itDTax law requires it

Submit answers