Invoice Service
serviceManages the lifecycle of invoices including creation, updates and retrieval.
- Owner
- Billing Team
- Technology
- TypeScript
- Runtime
- Node 20.x
- Surface
- 14 endpoints · 4 events
kimtu/invoice-servicedocs/overview.md3f9a2c1last commit 4 days ago by @mreyes
Written by the team in docs/overview.md · rendered by Kimtu, ownership and connections below are generated
Overview
Invoice Service is responsible for managing invoices for customers. It composes line items, applies tax, and hands finalised invoices to Payment Service for collection.
Scope
This service owns the invoice document and its line items. It does not hold payment state, ledger entries, or customer records — those belong to Payment Service, Ledger Service and Customer Service respectively.
- Draft, finalise and void invoices
- Apply tax rules per billing region
- Expose invoices to the gateway and to internal consumers
Lifecycle
An invoice moves through four states. Only finalisation is irreversible; a finalised invoice can be voided but never edited.
| State | Transition | Notes |
|---|---|---|
| draft | created | Line items are mutable. |
| open | finalize() | Emits invoice.finalized, locks the total. |
| paid | payment.settled | Set by the payment event consumer. |
| void | void() | Terminal. A credit note is issued separately. |
Finalisation is idempotent. Calling finalize() twice returns the same invoice and does not emit a second event.
Connections
UpstreamInvoice ServiceDownstream
| Component | Direction | Contract |
|---|---|---|
| API Gateway | Called by | REST /v1/invoices · Invoice, LineItem |
| Billing Cron | Consumes | POST /v1/invoices/{id}/finalize · Invoice |
| Customer Service | Calls | GET /v1/customers/{id} · Customer |
| Event Bus | Calls | amqp · invoice.created, invoice.finalized |
| Postgres · invoices | Calls | postgres · Invoice, LineItem |
| tax-rates | Calls | POST /rates · TaxRate |
Published events
events/invoice.created.json
1{2 "type": "invoice.created",3 "version": 3,4 "data": {5 "invoice": "in_9d41",6 "customer": "cus_8f21",7 "amount_due": 48200,8 "currency": "eur",9 "due_at": "2026-10-01T00:00:00Z"10 }11}Technology
TypeScriptPostgreSQLRabbitMQRedis