Invoice Service

Purpose: Node.js microservice for invoice management (create/sync invoices, totals, kitchen display orders, and related flows). It uses MySQL and Sequelize, targets a shared database with other services, and relies on manual SQL instead of Sequelize migrations.

User scope

This service targets master users only: payloads where line customization is expressed through modifiers and addons. It does not support non-master flows where customization depends on extras or materials instead of modifiers and addons.

API overview (/v1)

All routes below require Authorization: Bearer <jwt> unless noted. Tenant scope (customer_id, location_id) comes from the token.

Method	Path	Description
POST	/v1/invoices/sync	Sync invoice payloads; assign order_no / customer_invoice_id
PUT	/v1/invoices/:uuid/cancel	Cancel an invoice (status → cancelled, side effects via RabbitMQ)
GET	/v1/invoices/history	Paginated invoice history (sync-shaped orders)
GET	/v1/invoices/:uuid	Single invoice by UUID
GET	/v1/kds-orders	Kitchen display orders for the current business day
PUT	/v1/kds-orders/:uuid	Update KDS order (rebump, done_at, line items)
GET	/v1/dine-orders	Floor-plan tables with open/done dine-in invoices
GET	/v1/health/*	Health checks
GET	/health	Service liveness

Request/response contracts are defined in src/validations/ (Joi). KDS and dine-orders read responses use the same invoice payload shape as sync/history.

Inventory

Use the inventory module at the end of the invoice flow to call the inventory service for stock-related work. Inventory side effects run only after the order is completed—not for in-progress or abandoned orders.

Documentation (docs/)

Mobile frontend handout (Android / iOS)

Start here for native integration: docs/frontend-handout/00-INDEX.md

Document	What it covers
docs/frontend-handout/00-INDEX.md	Index + endpoint map
docs/frontend-handout/01-AUTH-AND-CONVENTIONS.md	JWT, flags, errors, Ably conventions
docs/frontend-handout/02-INVOICE-SYNC.md	POST /v1/invoices/sync
docs/frontend-handout/03-INVOICE-READ-CANCEL.md	History, get-by-UUID, cancel
docs/frontend-handout/04-KDS.md	KDS list + status + Ably
docs/frontend-handout/05-DINE-ORDERS.md	Floor-plan dine orders
docs/frontend-handout/06-PAYLOAD-REFERENCE.md	Full invoice / item field catalog

Engineering / internal API notes

Document	What it covers
docs/INVOICE_REQUEST.md	POST …/sync request body: shape, enums, examples
docs/INVOICE_RESPONSE.md	POST …/sync HTTP response envelope and data
docs/INVOICE_CANCEL.md	PUT …/cancel — cancel order, query/body params, RabbitMQ side effects
docs/INVOICE_HISTORY.md	GET …/history query params, response envelope, and sync-shaped orders
docs/KDS_API.md	GET …/kds-orders, PUT …/kds-orders/:uuid, Ably realtime, validation contract
docs/DINE_ORDERS_API.md	GET …/dine-orders — floor-plan tables with sync-shaped dine-in invoices
docs/INVOICE_REFACTOR.md	refactorInvoice() — fields, totals, item splitting