InvoiceCore 0.1.0

InvoiceCore

Zero-dependency invoicing primitives for .NET. Correct decimal money maths, multi-rate tax (inclusive and exclusive), status rules, JSON/CSV export. Bring your own storage and rendering.

Quick start

var svc = new InvoiceService();

var invoice = svc.Create(new CreateInvoiceRequest
{
    InvoiceNumber = "INV-001",
    IssuedDate    = new DateOnly(2025, 1, 15),
    DueDate       = new DateOnly(2025, 2, 15),
    CurrencyCode  = "USD",
    Customer      = new CustomerInfo { Name = "Acme Corp" },
    LineItems     = [new LineItem { Description = "Consulting", Quantity = 2, UnitPrice = 50m }],
    TaxRates      = [new TaxRate  { Name = "VAT", Percentage = 20m }],
});

Console.WriteLine($"Subtotal : {invoice.Subtotal:C}");   // $100.00
Console.WriteLine($"VAT 20%  : {invoice.TaxAmount:C}");  // $ 20.00
Console.WriteLine($"Total    : {invoice.Total:C}");       // $120.00
Console.WriteLine(svc.ExportToJson(invoice));

Tax arithmetic: worked example

Both modes produce the same correctly-rounded totals. Subtotal is always tax-exclusive: this is the value most likely to surprise callers switching between modes.

Exclusive mode (prices are net)

Line:  Qty 2 × $50.00 = $100.00
                         ───────
Subtotal (net)           $100.00   ← tax-exclusive in both modes
VAT 20%  on $100.00    =  $20.00
                         ───────
Total                    $120.00

Inclusive mode (same gross price, tax extracted)

// TaxMode = TaxMode.Inclusive, one line Qty 1 × $120.00, VAT 20%

Line total (gross):      $120.00
Subtotal  = Round($120.00 / 1.20) =  $100.00   ← tax-exclusive net
VAT 20%   = Round($100.00 × 0.20) =  $ 20.00
Residual reconciliation keeps Total = $120.00 exactly
                                      ───────
Total                                 $120.00

Note: Subtotal is the tax-exclusive net in both modes. In Inclusive mode it is the back-calculated base, not the gross line-item figure.

Multiple rates are additive, never compounded:

Subtotal              $1 000.00
VAT 20%    $200.00
Levy  5%   $ 50.00
           ───────
TaxAmount             $  250.00
Total                 $1 250.00

Rounding policy

All money arithmetic uses MidpointRounding.AwayFromZero (half-up), routed exclusively through a single internal Money.Round call site. There are no ad-hoc Math.Round or decimal.Round calls anywhere in the library.

Minor-unit precision is resolved per ISO-4217:

Unknown codes default to 2 digits and never throw.

What this is not

• Not a payment processor. No partial payments, payment allocation, or credit notes. Negative quantities are rejected in v1.
• Not a PDF renderer. Use InvoiceCore.Pdf (planned) for that.
• Not an accounting ledger. No bank feeds, journal entries, or chart of accounts.
• Not a tax jurisdiction lookup. You supply the rate; InvoiceCore applies it correctly.
• Not an e-invoicing compliance layer. Peppol, ZATCA, and FatturaPA are out of scope.
• Not a recurring-invoice engine. No schedules, templates, or auto-numbering.
• Not a currency converter. An exchange rate can be stored on an invoice for reporting grouping; it is never applied.

Prior art

InvoiceCore replaces the 400 lines of subtly-wrong tax arithmetic every SaaS team writes by hand, with no dependencies, no rendering, and documented, tested rounding behaviour.

Roadmap

License

MIT © 2026 Aftab Bashir