restaurant/docs/order-flow.md

Order flow

From "customer adds to cart" to "ticket prints in the kitchen", in one restaurant's slice. The customer-side aggregation across multiple restaurants is in webapp-integration.

State machine

   pending  ──pay──▶ paid  ──accept──▶ accepted ──ready──▶ ready ──serve──▶ completed
                      │                   │                  │
                      └─cancel────────────┴──────────────────┴─▶ canceled
                      └─refund────────────────────────────────▶ refunded

pending → paid is the only transition driven by money. All others are explicit calls to PUT /api/v1/orders/{id}/status/{new} from the cms.

States and their meaning:

State	Set by	Meaning
pending	services.place_order	Invoice issued, not yet paid
paid	invoice listener	LNbits payment settled (or cash recorded)
accepted	operator (or auto-accept)	Restaurant has acknowledged, prep in progress
ready	operator	Pickup-ready / served
completed	operator	Finished
canceled	operator	Pre- or post-payment cancel
refunded	operator	Paid → refunded

Place order

services.place_order(CreateOrder):

1. Resolves the restaurant; rejects if is_open=False.
2. Re-prices every line item against the live menu (modifier ids are matched server-side; the customer's claimed price_delta values are ignored).
3. Converts each item's price from its declared currency to msat. For sat-denominated items (currency ∈ {sat, sats, satoshi}) this is a flat × 1000. For fiat (USD, GTQ, …) it calls lnbits.utils.exchange_rates.fiat_amount_as_satoshis to look up the live rate, then × 1000. The conversion lives in services._price_to_msat so the rate lookup is the same path the quote endpoint uses — a customer's preview and the recorded order.total_msat cannot drift apart between request and place.
4. Sums subtotal_msat, applies tax_rate, adds tip_msat → total_msat.
5. For Lightning / internal: calls lnbits.core.services.create_invoice with extra={"tag": "restaurant", "restaurant_id": ...}.
6. Persists the order with id = payment_hash so the listener can look it up cheaply, plus one order_items row per line.
7. For cash: payment_method = "cash" skips invoice creation and marks the order accepted directly.

Returns (Order, OrderInvoice | None). The webapp pays the bolt11.

Pre-flight quote

POST /api/v1/orders/quote returns {"required_msat": <int>} for a hypothetical cart. The webapp sums the quotes from each restaurant before opening any per-restaurant invoice — so a customer with insufficient balance sees one error rather than partially-paid carts across N restaurants.

Settlement

tasks.wait_for_paid_invoices registers an asyncio.Queue listener on LNbits' global payment stream. On each payment:

if payment.extra.get("tag") != "restaurant":
    return
order = await get_order_by_payment_hash(payment.payment_hash)
if order:
    await mark_order_paid(order.id)

services.mark_order_paid is idempotent. It:

1. Sets order.status → "paid" (or "accepted" if settings.auto_accept_orders).
2. Decrements menu_item.stock for each line, clamped at 0.
3. Creates a print_jobs row.

Stock decrements happen at settlement, not at order placement — unpaid orders don't lock inventory.

Print pipeline

print_jobs is a queue. printer-pi (a separate process / device running outside this extension) picks up jobs via GET /restaurants/ {id}/print_jobs?status=queued, prints, and acknowledges via PUT /print_jobs/{id}/ack. Status flow: queued → sent → acknowledged, or failed with a last_error.

The roadmap calls for a Nostr-based push: printer-pi subscribes to the restaurant's pubkey for an order.confirmed event, removing the poll loop.

Multi-restaurant carts

A single customer cart spanning multiple restaurants is handled by the webapp-integration, not here. Each restaurant's extension instance only ever sees its own slice — its own order, its own invoice, its own print job. There is no umbrella order on the server side.

See also

• architecture
• data-model — orders, order_items, print_jobs
• webapp-integration — multi-restaurant aggregation
• nostr-layer — outbound status DMs (NIP-17, scaffolded)