Cloud sync not working

The booth is supposed to push transactions, heartbeats, and credit history to the BoothIQ cloud. When that pipeline breaks, you'll see it in the Cloud Sync tab. The status badge stays amber, the Sync Status card shows growing pending items, or the cloud dashboard never receives the booth's data.

Symptom: Cloud Sync status badge is "Not Registered" or stuck, pending items growing, no recent Last Sync timestamp.

Quick check first

  1. Open admin → Cloud Sync tab.
  2. Look at the status badge at the top right.
  3. Look at the Sync Status card on the right showing pending items and last sync time.
  • Connected (green) + 0 pending, recent Last Sync. Healthy. Nothing to do
  • Connected (green) + Growing, no recent sync. Booth thinks it's connected but cloud isn't accepting items
  • Not Registered (amber). Booth has never been registered, or registration was cleared
  • Error (red). Active connection error

Step 1: Confirm internet connectivity

Sync needs internet. Confirm the booth has it:

  1. Open the WiFi tab in admin.
  2. Check the Status card. Should say Connected.
  3. If you're on Ethernet, the WiFi tab will show "Not connected" but Ethernet will work. That's fine. The way to verify Ethernet is the next step.
  4. Open the Cloud Sync tab and look at Sync Status. If items are flowing, internet is fine. If they're not, see Step 2.

If WiFi is disconnected, see Connecting to Wi-Fi.

Step 2: Booth says "Not Registered"

If the status badge is amber and the booth has never been linked (or the link was cleared):

  1. Make sure the booth exists in your account and has an active plan.
  2. On the kiosk, open the Link This Booth card (or tap Activate at the bottom right of the welcome screen). It shows a QR code. If it says the code expired, tap Refresh QR.
  3. In the BoothIQ app, open the booth → Settings → Activate booth, and choose its subscription.
  4. Scan the QR code.
  5. The badge should turn green within a few seconds.

If registration fails repeatedly, see Cloud registration for the full walkthrough.

Step 3: Booth says "Connected" but pending items keep growing

The booth thinks it's connected, but items aren't getting through:

  1. In the Sync Status card, tap Sync Now.
  2. Watch the status badge and the pending items count for a few seconds.
  • Pending items drop and Last Sync updates. Credentials work and the cloud is accepting requests. It was just behind
  • Badge turns Error. Either the cloud is unreachable or it rejected the kiosk's credentials. Check Wi-Fi and the cloud dashboard first. If the cloud is reachable and the badge stays Error, the credentials were rejected (for example the API key was rotated): tap Unregister Booth, then scan the fresh QR code from the BoothIQ app to re-link with new credentials
  • Nothing changes and the badge stays Connected. The internet is up but the cloud is unreachable or refusing the items. Check Wi-Fi first; if that is fine, wait and try again, then see Step 5

Step 4: Last Sync is old

If the Sync Status card's Last Sync timestamp is more than a few minutes old but the status badge says Connected:

  1. Some sync activity is event-driven (it pushes immediately when something changes), some is on a timer.
  2. Take a small action that triggers a sync. Run a free-play customer session, or add credits manually in the Credits tab.
  3. Watch the Last Sync timestamp update within a few seconds.

If the timestamp doesn't update after triggering an event, the sync is broken. See Step 3.

Step 5: Pending items growing without limit

If pending items keep growing and never go down, the booth is generating events faster than it's syncing:

  • Most likely: sync is silently failing on some specific item (maybe a transaction with a malformed field). The booth retries but the cloud rejects it every time.
  • Less likely: the booth is generating an unusually high event rate and sync is slow.

This is rare. If it happens, contact support with the Booth ID and the pending items count. They'll need to look at logs.

Step 6: API key was regenerated in the cloud

If the booth's API key was rotated (for example by support after a suspected compromise), the old key on the kiosk is now invalid. Re-link:

  1. On the kiosk, Unregister the booth (red button on the Cloud Sync tab). The Link This Booth card shows a fresh QR code.
  2. In the BoothIQ app, open the booth → Settings → Activate booth, choose its subscription, and scan. The kiosk receives the new key as part of linking.

Step 7: Kiosk was moved to a different booth or account

To point a kiosk at a different booth, or at a booth in another BoothIQ account:

  1. Unregister the kiosk using the Unregister button.
  2. Sign in to the BoothIQ app with the account that owns the new booth, open that booth → Settings → Activate booth, and choose its subscription.
  3. Scan the QR code on the kiosk. The app warns you if the kiosk previously belonged to another booth; confirm to move it.

Selling the booth to another operator is different: use Transfer booth in the web dashboard so the buyer inherits the booth, its templates, and any remaining subscription time.

Step 8: When to call support

Contact support if:

  • Pending items grow continuously and never sync
  • The status badge shows Error even after unregistering and scanning the QR code again
  • The booth is registered in the cloud dashboard but appears as Offline despite being online and reachable
  • Cloud-driven commands (e.g. add_credits from the cloud) aren't reaching the booth
  • Sync was working and suddenly stopped without you changing anything

Have the Booth ID, the Cloud Sync status, and a description of what you tried.

Working without sync

The booth is offline-first. Sync isn't required for the customer experience. If sync is broken and you don't have time to fix it:

  • Customers can still buy sessions and print photos
  • Sales are recorded locally
  • Credits work normally
  • The only thing you lose is cloud monitoring and remote commands

When sync comes back, the booth will catch up the queued items automatically.

Common causes

Booth never registered.

Run cloud registration.

Network drop.

Reconnect Wi-Fi or check Ethernet.

API key regenerated.

Unregister, then scan the QR code again from the BoothIQ app.

Kiosk moved to another booth or account.

Unregister, then scan from the account that owns the new booth.

Cloud API outage.

Wait and retry.

Bad data in pending queue.

Contact support.

Verify it worked

Sync is healthy when:

  • Status badge is Connected (green)
  • Pending items is 0 or close to it
  • Last Sync is recent (within the last minute)
  • A test action (e.g. add credits in admin) immediately appears in the cloud dashboard
  • The booth shows up as Online in the cloud dashboard

Next steps