Building an Invoicing System: 12 Developer Pitfalls
What goes wrong when developers build invoicing: float money, VAT rounding, gap-free numbering, immutability, e-invoicing and audit trails.
Editorial disclosure: Pyalm publishes and maintains the products and free tools discussed on this site. Regulatory statements are linked to primary sources where applicable. No independent professional review is claimed unless a reviewer is explicitly named.
Invoicing looks simple — a table, a PDF, a total. Then the first customer asks for VAT, a credit note, a different currency or an audit trail, and the "simple" module becomes the hardest part of the product. These are the pitfalls we see most often.
1. Floating-point money
0.1 + 0.2 is 0.30000000000000004 in JavaScript and most languages. Never store or add money as binary floating point. Use integers in minor units (fils, cents) or a decimal type, and format only for display. Details in floating-point money bugs and rounding.
2. Currencies don't all have two decimals
AED, USD and EUR have 2; JPY has 0; KWD, BHD and OMR have 3. Store the currency code with every amount and look up the minor-unit exponent — don't hard-code 100.
3. VAT rounding
Do you round tax per line or per invoice? The two can differ by a fils or more, and tax authorities may expect a particular approach. Pick a documented rule, apply it consistently, and make the invoice total equal the sum of the displayed parts so customers can re-add it.
4. Gap-free sequential numbering
Tax invoices are expected to be sequential and unique. A database sequence or auto-increment skips numbers when a transaction rolls back. Gap-free numbering needs deliberate design: allocate the number at the moment of finalisation, inside the same transaction, per series, per legal entity and per year if required. See missing invoice numbers.
5. Immutability
A finalised invoice must not change. Corrections are made by a credit note and a new invoice, not an edit. Store a snapshot of the customer's name, address, tax number and prices at issue time — otherwise changing a customer record rewrites history. See credit note vs debit note.
6. Tax rules are data, not code
Standard, zero-rated, exempt and out-of-scope supplies; reverse charge; place of supply; different rates by country. Model tax codes and rules as data with effective dates, so a rate change doesn't need a deployment. See zero-rated vs exempt supplies and what a UAE tax invoice must contain.
7. Time zones and dates
Invoice date, supply date, due date and posting date are different things, and "today" depends on the time zone. Store dates without times where only a date is meant, and timestamps in UTC where time matters.
8. PDFs are a presentation, not the record
The record is the structured data. Generate the PDF from it, store it with the invoice, and keep the layout version that was used. Bilingual Arabic/English layouts add right-to-left text, fonts and shaping issues.
9. E-invoicing
Several markets, including the UAE, are moving to structured, machine-readable e-invoices exchanged through accredited networks. A PDF emailed to the customer won't satisfy that. See the UAE e-invoicing guide and e-invoice vs PDF invoice.
10. Payments, partial payments and credit
Invoices get part-paid, overpaid, refunded and written off. Model payments and allocations separately from invoices, or your receivables will never reconcile. See AR ageing.
11. Audit trail and permissions
Who created, edited, approved, voided? Without a log, you can't answer an auditor or investigate an error. See audit trail in accounting software.
12. The accounting side
Every invoice must post to a ledger with balanced debits and credits, VAT control accounts and receivables. That's a double-entry engine, period locking, bank reconciliation and reporting — a product in its own right. See journal entries explained.
So: build or buy?
If invoicing is your product, build it — with the above in mind. If it is a supporting feature of something else, or if you simply need to run your business books, don't. Use accounting software that already gets the tax, numbering and ledger right. Pyalm Books handles UAE VAT, invoices, credit notes, purchases, POS, inventory, banking and reports on a double-entry ledger, free during beta. See also build vs buy for your app.
If you do need something custom — an integration, a portal, a workflow around invoicing — Pyalm builds exactly that. See custom software development or talk to us.