Offline-first billing: what actually breaks when the internet dies

It’s 8:40 on a Saturday night. The restaurant is full, the kitchen is two tickets behind, and the broadband light goes red. In a demo, this is where the story ends. In a real restaurant, the next ninety minutes decide whether the team trusts your product.

We built the billing engine behind Zynibill to keep working through that. The lesson wasn’t that offline mode is hard to switch on. It’s that offline mode changes almost every assumption in the system.

The minimum offline surface

Write down what must happen with no internet. Not “everything”, and not “view the menu”.

• Create an order at a table.
• Add or remove items, modifiers, and quantities.
• Send a kitchen order ticket (KOT).
• Print the bill.
• Record cash or a confirmed UPI payment.
• Close the table and open or close the shift.
• Reprint a bill and see basic day totals.

Everything else — menu publishing, analytics, loyalty, supplier reports — can wait. The moment you blur that line, scope explodes and the important path gets slower.

Three layers, not one clever browser tab

Local-first doesn’t mean “store it in localStorage and hope”. In a single-counter café, a durable browser database may be enough. In a multi-terminal restaurant, you need a local hub on the LAN so the cashier and captain see the same table state even when the router is out.

The cloud is still the source of truth for configuration and long-term reporting. It just can’t be the only place a sale exists.

The local write path is the product

The rule is simple: a button that creates a sale must not wait for a network response. Save locally, update the UI, print, then queue the sync. If the handler awaits the cloud before printing, you built a cloud app with an offline sticker.

If the bill button waits for a server response before printing, the internet is part of your cash counter. That’s a design choice, and a bad one.

Each sale gets a client-generated ID, a sequence, a timestamp, and an idempotency key. The server accepts the same event twice without creating two bills. Retries are normal; duplicates are not.

type PendingSale = {
  localId: string;
  idempotencyKey: string;
  payload: Sale;
  attempts: number;
};

// 1. Persist locally first.
await localDb.sales.put(sale);

// 2. Queue the sync. This can fail without losing the sale.
await localDb.outbox.add({
  localId: sale.id,
  idempotencyKey: crypto.randomUUID(),
  payload: sale,
  attempts: 0,
});

Conflict rules you must decide before launch

Every offline system needs an answer to “who wins?”. Most teams discover theirs during the first busy weekend. Decide in writing instead.

The dangerous conflicts are operational, not technical: table 12 was moved, a bill was split, a discount was applied after the KOT went out. Pick an explicit rule and show it to staff in plain language.

GST invoice numbering is the trap

A tax invoice is not a receipt you can renumber after sync. If bills are issued offline, the series must be allocated before the network drops.

• Give each terminal a pre-allocated block or its own clearly identifiable series, and never reuse a number.
• Do not renumber an issued bill after sync. If something is wrong, issue a credit note or cancel it under the applicable rules.
• Keep the series consecutive within the financial year and store the audit trail.
• Test the approach with your CA before the first offline shift. Rules and state requirements vary.

Our GST invoice checklist covers the field-level rules. They don’t change because the printer is in a hurry.

Make sync state impossible to ignore

A tiny cloud icon that turns green is not a reconciliation workflow. Staff need to see how many bills are pending, which ones failed, why, and what to do next.

• A pending badge on every unsynced bill.
• An exception drawer with the error and a retry action.
• A warning at shift close when payments or totals don’t reconcile.
• A manager override with a reason, not a silent bypass.
• An export for the accountant.

We blocked shift close when the exception queue had unresolved payment mismatches. It annoyed people for exactly one week. Then it saved a month-end reconciliation.

Test like the network hates you

1. Pull the router mid-bill and confirm the bill still prints.
2. Throttle to 2G and watch the sync retry without freezing the UI.
3. Refresh the browser at the payment step.
4. Double-tap the bill button and confirm the server creates one bill.
5. Sell the last item from two terminals at the same moment.
6. Turn the printer off, take an order, and recover.
7. Move the device clock and check timestamp handling.
8. Run a 24-hour outage, then reconcile the next morning.

Airplane mode is the easy test. Real outages are intermittent, slow, and happen during the busiest hour. Use a network throttle and a router you can switch off without warning.

What Zynibill taught us about trust

The billing engine runs offline and prints a bill in under two seconds on the local path. The feature that mattered most wasn’t the sync algorithm. It was giving staff a clear, boring answer to “did this go through?”

We also stopped treating offline as a fallback. It’s a first-class mode with its own state, tests, and support script. The cloud is a reporting and configuration layer, not a dependency on the critical path.

A short implementation checklist

• Define the offline write path and the local source of truth.
• Add an outbox with retries and idempotency keys.
• Pre-allocate invoice series with your accountant.
• Show sync state at the bill and shift level.
• Build a reconciliation report before launch.
• Test on the actual counter hardware, not just a laptop.
• Write a one-page downtime script for staff.
• Run a monthly downtime drill.

The promise, not the database

Offline-first is not a database feature. It’s a promise to the cashier: the next sale will work. Keep that promise on the local path, make the reconciliation honest, and treat the cloud as the place where records live — not the place where the next bill waits.