Document automation · Implement
Invoice JSON Schema: A Practical Document Contract
Design an invoice payload that separates accounting calculations from visual template presentation.
For developer · 8 min · Reviewed Jul 31, 2026
Model the document, not the database
Expose stable company, customer, invoice, line-item, subtotal, tax, total, payment, and note fields. Avoid leaking internal records or forcing templates to understand database relationships.
Supply calculated values
The billing system remains authoritative for quantity, unit price, discount, tax, subtotal, and total calculations. Send final values to the renderer rather than implementing accounting logic in bindings.
Use explicit display context
Supply the currency code or already formatted value according to one documented contract. Include dates in a stable format and decide whether localization happens before or during presentation.
Test difficult fixtures
Keep fixtures for no optional notes, long addresses, many line items, zero-value items where allowed, alternate tax states, paid/unpaid display, and every supported locale.
Version contract changes
Coordinate schema additions and removals with template versions. Validate application fixtures against staging before promoting the same immutable version to production.