Connect an ERP POS to a Bluetooth Printer With Flutter

An ERP knows what a sale is worth. A Bluetooth printer knows how to burn dots onto paper. Everything painful in a mobile point of sale lives in the gap between them, and that gap is wider than it looks: the network can be gone for hours, and the printer will never tell you that the customer actually got their receipt.

This is the architecture I use to close that gap, built around one principle — the device must be able to complete a sale and print it with no server, then reconcile later without ever duplicating a receipt.

Two unreliable links in series

Drawing the system honestly is the first step, because it shows that the two failure domains are independent and must be handled separately.

ERP (source of truth)
   |  sale document, tax rules, prices, stock
   v
Sync API  ---- intermittent, may be offline for hours
   |
   v
Flutter app (device)
   |  local sale record  ->  outbox  ->  printer job
   v
Bluetooth SPP  ---- 58 mm printer, no acknowledgement of "printed"

// Two independent unreliable links, in series. Every design decision
// below exists because a failure on either side must not lose a sale
// and must not print a receipt twice.

The ERP link fails slowly and visibly: a request times out, a sync job backs up, someone notices. The printer link fails instantly and silently: the bytes were written, the socket accepted them, and whether paper moved is unknown. Designing one retry policy for both is how apps end up printing four copies of one receipt.

What belongs on the device and what belongs in the ERP

The split is not obvious, and getting it wrong produces either an app that cannot sell offline or an ERP that cannot be trusted. My rule is that the ERP owns meaning and the device owns events.

• The ERP owns prices, tax rules, product master data and the definitive ledger. The device caches them and never invents them.
• The device owns the fact that a sale happened at a moment, with a locally generated identifier that the ERP later adopts rather than replaces.
• The device owns everything physical: which receipt was printed, how many copies, whether the drawer opened. None of that belongs in the ERP's sale document.
• Reconciliation is a background job, not a checkout step. A cashier should never wait for a server to acknowledge anything.

Generating the sale identifier on the device is the detail that makes the rest work. It gives you a stable key for the print job, the outbox row and the eventual ERP document, so a retry at any layer refers to the same real-world event.

The print job table, and why it has a unique constraint

Print jobs live in local storage next to the sale, not in memory. Persisting them is what lets the app survive being killed mid-print, and the unique constraint is what keeps a nervous cashier from producing four identical receipts.

-- Local SQLite on the device. The ERP never sees this table; it is
-- the device's own memory of what physically happened.
CREATE TABLE print_job (
  id            TEXT PRIMARY KEY,        -- uuid v4, generated on device
  sale_id       TEXT NOT NULL,           -- the local sale it belongs to
  copy_index    INTEGER NOT NULL,        -- 0 = original, 1..n = reprints
  payload       BLOB NOT NULL,           -- the exact ESC/POS bytes
  state         TEXT NOT NULL,           -- queued | printing | done | failed
  attempts      INTEGER NOT NULL DEFAULT 0,
  last_error    TEXT,
  created_at    TEXT NOT NULL,
  UNIQUE (sale_id, copy_index)
);

-- The unique pair is the idempotency key. A tap-happy cashier pressing
-- "print" four times produces one original and three explicit reprints,
-- not four indistinguishable receipts.

Modelling reprints as an explicit copy index rather than as repeated attempts has an operational benefit too: a reprint can be marked visibly on the paper, which is what an auditor and a shop owner both want when a customer arrives with two receipts for the same sale.

Treat the printer as a port

The single design decision that has paid off most is refusing to let Bluetooth types leak upward. Everything above the transport talks to a small interface, and that interface has three implementations.

/// The printer is a port, not a feature. Everything above it — the
/// receipt builder, the queue, the ERP sync — depends on this
/// interface, so the app can be tested and demoed with no hardware.
abstract interface class ReceiptPrinter {
  Future<bool> isAvailable();
  Future<void> send(List<int> bytes);
}

class BluetoothReceiptPrinter implements ReceiptPrinter { /* real device */ }
class FilePrinter implements ReceiptPrinter { /* writes .bin for tests */ }
class NoopPrinter implements ReceiptPrinter { /* demo mode, no device */ }

// Swapping FilePrinter in during integration tests is what let us run
// the entire checkout flow in CI, on a machine with no Bluetooth at all.

The payoff shows up in three places. Integration tests run the whole checkout flow in CI against a file-writing printer. Sales demos run in a hotel room with no hardware. And when a client asked for a network counter printer alongside the portable one, the change was a new implementation of the same interface, not a change to the sale flow.

Reconciling what printed with what the ERP believes

Once the device can sell and print offline, you need a story for the day after. Three habits keep it manageable.

• Sync the sale first and the print metadata second. The financial record matters more than the fact that a piece of paper was produced.
• Include the local sale identifier in the ERP document, so support can move from a paper receipt to an ERP record with one search.
• Report unsynced sale counts and unprinted job counts in the app, on the same screen, visible to the shop rather than only to you.

That last one changed how installations went for me. When staff can see two numbers that should both be zero at closing time, they raise problems on the day rather than at month end.

Rolling it out to real shops

The technical design is half the work. This sequence has made the installs uneventful.

1. Ship with a printer settings screen that can discover, select, test and forget a printer, so an install needs no developer.
2. Pilot in one shop for a full week, including a weekend, before promising anything. Weekday volumes hide every battery and reconnect problem.
3. Watch the two counters — unsynced sales and unprinted jobs — daily for that week, and treat any nonzero closing value as a bug rather than as noise.
4. Write a one-page shop-facing runbook: printer will not connect, printer prints garbage, receipt did not come out. Three headings, three answers.
5. Only then roll out to the rest, one shop per day, so a bad interaction with a particular device model surfaces once rather than everywhere.

The runbook is the highest-leverage artefact in that list. Most support calls are pairing, battery or paper, and a shop that can resolve those alone will call you only about the interesting failures.

Connecting an ERP to a Bluetooth printer is an exercise in accepting that neither link is reliable and designing so that neither can lose money or duplicate paper. A local job table with a real idempotency key, a printer interface you can fake, and two counters the shop can see will cover almost everything a field deployment throws at you.