Troubleshooting Sync

Almost everything drains on its own. This page is for the cases that do not: a count that will not fall, and a red Sync Failed badge that will not clear however long you wait.

Read Sync status first if you are not sure which state you are looking at.

Before anything else: what not to do

Never reinstall Kassly, clear its data, or reset the tablet while anything is pending. The device is the only copy of an unsynced sale. Wiping the app destroys that money permanently, and no amount of support can recover it. Get the count to zero first.

Never sign in as a different business on a device with pending sales. Switching to another business wipes the device clean, outbox included, so tenant A's sales can never be posted under tenant B's login. If you run more than one business, sync the device to zero before switching. See Multiple businesses.

Signing out of your own account is safe. Unsynced sales survive a logout, and a session timeout, and they drain the next time the same business signs in on that device. This matters because "sign out and sign back in" is one of the fixes below.

Start here

What you see	Go to
Amber count that is not falling	An amber count that will not move
Red badge, count rising, genuinely no internet	Nothing is wrong. Keep selling
Red badge but you believe you have internet	The badge says offline and you do not think you are
Sync Failed on one or more sales	Clearing a Sync Failed sale
A shift you closed offline has not appeared on the web	A shift or cash movement that has not arrived

An amber count that will not move

Amber means Kassly can see the server and is working through the queue. Tap the badge to force an attempt rather than waiting for the next minute.

If the count still does not fall, work down this list.

1. Give it two minutes. Kassly retries every 60 seconds and sends up to 100 sales per attempt. A long offline stretch takes several passes.
2. Check it is not the server. If Kassly gets a server error or a timeout, it treats that as "not this sale's fault", puts the sale back to pending without marking it failed, and stops hammering until the next attempt. So during a Kassly outage or a very slow link, a static amber count is the expected behaviour, not a jam. It will drain by itself when the server recovers.
3. Check what is actually queued. The count includes shift opens, shift closes and cash movements, not only sales. Open Sales history: if no sale shows Pending Sync but the count is 2, the queue is holding shift work.
4. Look for a red row. One Sync Failed sale keeps a permanent entry in the count. It does not block the others — see below — but it does keep the number above zero forever.
5. Move to better signal, or a different network. Switching from mobile data to Wi-Fi, or the reverse, forces an immediate attempt as soon as the link changes.

A single red row does not hold up the rest. If Kassly sends a batch and the server rejects the whole batch, it re-sends every sale in it individually so the good ones get through and only the genuine offender stays failed. If you see one red row surrounded by green, that mechanism did its job.

The badge says offline and you do not think you are

Kassly tests whether it can reach the server, not whether the phone has a signal. Full bars and a red badge means the network is up but not usable.

Cause	What to try
Wi-Fi needing a portal login	Open a browser on the device and load any page. Log in to the network, then come back
Congested mobile data	Move, or switch to Wi-Fi. The badge clears on the first successful check
App just opened	Wait a few seconds. It reads offline until the first check answers
Connection genuinely just returned	Wait up to a minute. Kassly needs one successful check, and clears immediately when it gets one
Something blocking Kassly on the network	A guest or corporate Wi-Fi may be filtering it. Test on mobile data

Sync sometimes succeeds while the badge is still red, because syncing tolerates a slower connection than the badge check does. If the count is falling, ignore the colour.

Clearing a Sync Failed sale

Red means the server looked at the sale and refused it. Retrying identically will be refused identically, so something has to change first.

Tap the red row. It opens the recovery dialog rather than a receipt, and the dialog shows you the reason the server gave.

Match that message here.

Message	Cause	Fix
"Session expired — sign out and sign back in to sync this sale."	The device's login was rejected	Sign out and back in on that device. Your pending sales survive it. Then tap Retry
"Transaction pending: payment may not cover total."	The sale reached the server but its payments do not add up to the total, so it is sitting there unfinished	Contact support with the receipt number. Do not re-ring the sale — it exists
A message naming a specific field	The sale carries something the server will not accept	See below
"Server rejected transaction"	No specific reason came back	Export the CSV and contact support

For the "attach a customer" case, the dialog does the work for you. This is by far the most common rejection in practice: a sale — usually a membership sale — was rung up offline against a customer who was also created offline, and the link between the two did not survive the trip. The dialog lets you Attach Customer: pick an already-synced customer from the list, and Kassly re-sends the sale attached to them.

Two things about that list: it only offers customers the server already knows about, and that is deliberate. Picking another offline-only customer would reproduce the original problem. If the right person is not there, get them created online first — the Customer profiles page covers that — and then come back.

Retry on its own resets the sale's error and attempt count and tries again. Use it after fixing the cause, not instead of fixing it.

When a sale genuinely will not go

Some rejections cannot be fixed from the app — a field the server considers invalid, for instance. In that case:

1. Open Sales history and tap Export CSV. The file includes a Source column and a Sync Status column, which tells support immediately which side of the fence each sale is on.
2. Send that file with the receipt numbers of the red rows.
3. Leave the rows alone. They are the only record of that money. Kassly never deletes a failed sale — not on housekeeping, not when a new shift opens, not ever — precisely so this conversation is possible.
4. Do not re-ring the sale to "get it into the system". You will duplicate real revenue, duplicate the stock movement, and duplicate the BIR receipt.

A shift or cash movement that has not arrived

Shift work queues like a sale, so the usual answer is that it is still in the queue. Two specific cases:

• You closed the shift offline and the web shows it open. Expected. The close is queued. The official Z-reading is generated when it lands, which is why the offline close is labelled as this device's own records. See X and Z readings.
• You could not open a shift at all, with "Branch information is missing — reconnect to the internet so the app can restore your account, then try again." This is the one shift action that offline cannot queue: the device does not know which branch it belongs to, and a shift with no branch would be rejected forever. Get online once and it repairs itself.

Cash In and Cash Out recorded offline are confirmed as Recorded Offline and fold into the offline X-reading, so your shift still reconciles against the drawer while they are queued. See Cash over and short.

Things that are not sync problems

A few common reports look like sync failures and are not.

Symptom	What it actually is
A price or a product is wrong on the till	The local catalogue is stale. Get online and let it refresh
Stock on the till disagrees with the web	Same cause. Offline stock is as of the last sync
A table's status is wrong on the web but right on the till	Table statuses set on a device are never sent up. See What works offline
A stock adjustment you made "disappeared"	It was never saved. Adjustments do not queue offline
A staff punch is missing	The one-tap self punch does not queue offline. Station mode does
An online order you accepted did not process	Accepting an order offline is not queued
Sales missing from Terminal Performance	Not a sync fault — see Sales reports

Preventing the next one

Habit	Why
Get the badge to green before you close for the day	The outbox is the only copy
Pair every device to a till	Unpaired devices issue OFL- receipts that no report can attribute
Open the app on Wi-Fi at the start of a shift	It syncs the catalogue, and the staff roster the PIN checks need
Create customers online where you can	The offline-customer link is the most common rejection
Sync a device to zero before switching business	Switching wipes the device