POS storage, sync, and device administration

StoreConnect POS runs entirely in the browser and uses browser storage technologies to maintain a local copy of your organization’s data on each device. This enables fast, responsive operation even under varying network conditions.

Storage architecture

IndexedDB

POS stores all product, customer, order, and inventory data in IndexedDB, a built-in browser database designed for large volumes of structured data. Key points:

• IndexedDB survives page refreshes, browser restarts, and standard cache clears.
• POS asks the browser to keep this storage persistent each time it starts. When the browser grants the request, it does not delete the register’s data to free up space when the device runs low on disk.
• It is a standardized web technology supported by all modern browsers.
• Storage size varies by device and with the size of your catalog and transaction history. It can reach several hundred megabytes, or over a gigabyte on large datasets.

:::warning IndexedDB is not cleared by a standard cache reload (Ctrl+Shift+R / Cmd+Shift+R). Only using the browser’s “Clear All Site Data” or “Clear Storage” developer tools option will wipe it. :::

Local Storage

The POS keeps a small amount of information in the browser’s Local Storage so it doesn’t have to start from scratch every time it opens. This includes:

• The secure key that lets the register identify itself to StoreConnect (so it stays connected without signing in again each time).
• A saved snapshot of what the POS was doing, so it can pick up where it left off when the page reloads.

Once the POS is up and running, this stored information is only used to get started. The POS doesn’t keep saving live sales data there as you work.

Storage comparison

Storage	Purpose	Survives cache clear?	Survives “Clear All Site Data”?
IndexedDB	Product, customer, order data	Yes	No
Local Storage	Auth token, session state	No	No

What happens when Local Storage is cleared

If Local Storage is cleared (for example, via a cache reload or browser setting):

1. The API token is removed, disconnecting the register.
2. POS detects the missing token and automatically redirects to the login screen. This is a handled transition, not an error state.
3. The user is prompted to re-login and re-register the device.
4. IndexedDB data is preserved, so products, customers, and orders remain intact.
5. Once logged back in, POS reconnects to the existing IndexedDB database. A full re-sync is not required.
6. The POS syncs to catch up on anything that changed while it was offline, updating only what’s new rather than reloading everything.

Sync process

Initial sync

When a device is set up for the first time, or after a full data wipe, POS performs an initial sync that downloads every record the register needs from the server.

• The register opens once the first records of each object have loaded. The rest of each object then downloads in the background while staff work. Most records arrive most recently changed first, so recently edited products and customers are available before older history. Orders and order fulfillments are the exception: they download oldest first, so today’s orders and fulfillments are the last to arrive.
• Records are downloaded in pages over standard web requests, and the network load is minimal. Most of the time goes on writing records to IndexedDB, so the speed depends mainly on the device hardware. An older or lower-powered device can take much longer than a newer one.
• Until an object finishes, a lookup can miss older records that have not arrived yet.

Keeping up to date

After the initial sync, the POS keeps itself current by downloading only what has changed. For products, customers, carts, and other records:

• About once a minute, the register asks the server for records changed since the last check.
• A change made at another register in the same outlet reaches a connected register straight away, without waiting for the next check.
• New changes keep arriving while older records are still downloading, so the register does not have to finish the initial sync before it sees today’s updates.

:::note Orders and order fulfillments sync differently. Two changes reach connected registers in the same outlet straight away: a new order that has fulfillments, and a fulfillment created or changed at another register. Every other order change, including an edit to an existing order, arrives at the register’s next regular sync check. :::

Screens refresh once when a batch of updates finishes, rather than redrawing after every page. The orders list keeps the current rows on screen while new orders arrive, and shows a spinner only on first load or when the search or filters change.

Follow sync progress

While the register starts, POS shows a loading screen that names the current step: Loading schema, Opening database, Starting sync worker, then Loading initial records.

To follow the download, open Settings, then Manage data. Each object shows a count such as Syncing 1,234 of 2,000 while it downloads and Synced 2,000 of 2,000 when it is complete. See Manage POS data sync.

How deletes reach other registers

When a register deletes a record, StoreConnect also deletes the records that depend on it, and sends every one of those deletes to the other registers. For example, when a cart fulfillment is removed, the fulfillment items that link cart items to it are removed too. Other registers drop the fulfillment and the linked items together, so no register is left holding items that point to a fulfillment that no longer exists.

• A register in the same outlet that is connected at the time removes the records straight away.
• Every other register removes them at the next check, normally within a minute.
• A delete made while the register is offline is held on the register as an unsaved change, and reaches the other registers once it uploads.
• A record deleted in Salesforce takes longer, because StoreConnect processes Salesforce deletions every 10 minutes. Allow 10 to 15 minutes before it disappears from registers.

This applies to every delete a register makes, including deletes from the record:delete action in a custom action.

Day-to-day best practices

Avoid wiping data unless necessary

Clearing IndexedDB data should be a last resort. A full wipe means the device must repeat the initial sync, which:

• Takes significant time (up to an hour or more, depending on hardware).
• Puts the device under load while syncing.
• Means some records won’t be available for immediate lookup until the sync catches up.

Handling authentication issues

Before wiping any data:

1. Try a simple page refresh first.
2. If the register has lost the connection, sign in and connect the register again. IndexedDB data is preserved, and POS catches up by downloading only what changed.
3. POS data is self-healing, and in most cases reconnecting the register resolves the issue.

Selecting Disconnect on a register is not a reconnect. It wipes all local data on the register, and the next sign-in runs a full initial sync. Use it only when you intend to start the register again from scratch. See Disconnect a POS register.

When a data wipe may be necessary

A full data wipe is only warranted if:

• There has been a significant reconfiguration of the database schema that a refresh has not applied.
• POS is experiencing persistent errors that cannot be resolved by reconnecting.
• StoreConnect Support has specifically advised a data wipe.

If the POS is unresponsive and reconnecting does not resolve the issue, see Reset an unresponsive POS for step-by-step recovery options before considering a data wipe.

StoreConnect upgrades

How upgrades work

StoreConnect is a cloud application, so upgrades are org-wide and apply to all devices simultaneously. POS picks up application updates on page refresh. Devices do not need to be individually updated.

Occasionally, an upgrade may include database schema changes (for example, new fields or new indexes).

Schema changes during upgrades

The data schema is rebuilt on app boot only. A page refresh in the browser, or closing and reopening the native app, is what triggers it. The data sync actions under Settings then Manage data do not rebuild the schema: they clear and re-download records in the tables the device already has. This matters when an object is newly added, because only a boot creates its table. See Manage POS data.

When POS detects a schema change after a page refresh:

1. POS displays an “Initializing” spinner while it applies the database changes.
2. POS is inaccessible during this time. Users cannot process transactions until the migration completes.
3. Duration depends on the size of the schema changes. Minor additions are quick, and larger restructures take longer.

Upgrade best practices

• Always test upgrades in a sandbox environment first before rolling out to live store devices. This lets you gauge the impact of any schema changes and estimate downtime.
• Schedule upgrades during off-peak hours when possible, to minimize disruption if schema migrations are required.
• StoreConnect changes are generally additive — new fields and indexes are added rather than existing ones removed or altered. Destructive schema changes are extremely rare and will be communicated in advance.
• After an upgrade, monitor a few devices to confirm they have successfully applied the changes before resuming normal operations across all registers.

Why a custom field or object has not reached the device

This is the most common cause of a register that looks correctly configured and shows nothing. Two different mechanisms are involved, and doing only one of them is the usual mistake.

A Custom Data Mapping does not put anything on the device. The device’s schema is built from POS Layouts. Each layout’s object becomes a table on the device, and the fields that sync into it are that layout’s POS Layout Fields, plus any field used by its filters or its sort order. An object with no POS Layout has no table on the device at all, no matter how many Custom Data Mappings name it.

The two do different jobs. A Custom Data Mapping makes a Salesforce field or object available to the store. A POS Layout Field is what puts it on the register.

The order that works

1. Deploy the custom object or field as metadata.
2. Give the sync user read access to it. A field the sync user cannot see behaves as though it does not exist.
3. Create the Custom Data Mapping for the object and field. See Surface a custom object in Liquid.
4. Create the POS Layout for the object, and a POS Layout Field for each field the register needs.
5. Boot the app on the device.

Skipping step 4 is what produces an empty screen with a configuration that reads as complete.

Only a boot builds the table

A new object’s table is created when the app boots, not when data is synced. Refreshing the browser or closing and reopening the native app is what rebuilds the schema. The actions under Settings then Manage data clear and re-download records in tables the device already has, so they cannot create a table that does not exist yet. This is covered in schema changes during upgrades above, and it applies equally to a field or object you have just added.

A second open tab can block the rebuild

The schema rebuild needs exclusive access to the local database. Another tab holding the old version open prevents the version check from completing, and POS logs probe blocked by another connection to the console before falling back. A refresh in one tab is not enough when a second tab is still open on the same register. Close every other POS tab and window on the device, then reload.

If the local database stays locked for 15 seconds at start-up, the POS stops with We couldn’t load your register and Failed while: Opening database. A tab or window that is frozen, minimized, or open in another browser profile can hold the lock without showing anything. Closing the other copies and selecting Refresh is the fix, and recovering from that screen gives the full order of steps.

Which fields the device indexes

A list or grid layout builds device indexes for these fields automatically:

• Every POS Layout Field whose Type includes Indexed. A field with Type Field, or with no type, counts as indexed.
• Every field used by the layout’s filters.
• Every field in the layout’s sort order.

Record and form layouts do not add indexes, and neither does a layout field whose Field Name uses dot notation to reach a related record. See POS layouts for the Type values.

A change to which fields are indexed applies the next time the app boots on the device. The device builds the new index over the records it already holds, so no resync is needed.

This is separate from the Indexed checkbox on a Custom Data Mapping, which builds an index in the StoreConnect database rather than on the device. See Add custom data fields to your store.

A saved record is local before it is in Salesforce

The record:save action writes to the device’s own table and queues the change for upload. It does not write to Salesforce as it runs, so reading the value back on the device confirms only that the local write happened.

• The action only works on a table whose primary key is the StoreConnect external ID, s_c__sc_id__c. That covers the StoreConnect objects the device holds, such as the cart, cart items, contacts, shifts, and the POS configuration records. Supplying an s_c__sc_id__c updates an existing record; leaving it out creates a new one.
• It cannot target a custom object. A custom object’s device table is keyed on sfid, not s_c__sc_id__c, so record:save raises record:save action requires a table with s_c__sc_id__c primary key. To write back to a custom object from the register, use an action that calls out to Salesforce rather than the local-table route.
• To confirm a change actually reached Salesforce, check that Unsaved records for that object is zero under Settings then Manage data, then open the record in Salesforce. See Manage POS data sync.

Debugging POS devices

Browser-based POS (desktop/web)

If the “Initializing” spinner is taking excessively long or POS appears stuck:

1. Open the browser’s Developer Tools (F12, or right-click and select Inspect).
2. Navigate to the Console tab.
3. Look for any red error messages. If there are no errors, the process is likely still running normally and may just be taking longer due to data volume or device hardware.
4. Common console messages during sync include progress updates for record inserts. These are normal.
5. If you see repeated authentication errors or network failures, check the device’s internet connection and try refreshing the page.

POS native application (Android/iOS)

1. Tap the three dots (…) in the bottom right-hand corner of the screen.
2. Select Show Logs from the menu.
3. Enter the register PIN code for this register.

:::note This is the PIN you set for the register when adding it to the Android app, not the day-to-day user PIN that staff enter when signing in to a shift. The Android app supports multiple registers, each with its own PIN to control access. :::

1. Review the log output for errors. If there are no obvious errors, the process is likely still running and just needs more time.

Log patterns

Log pattern	Meaning
No errors, sync messages visible	Sync is running normally — wait for it to complete.
Authentication errors	Session may have expired. Try re-login.
Network/fetch errors	Check internet connectivity.
Quota exceeded errors	Device storage is full. Free up space or contact StoreConnect Support.
Repeated errors for the same object	Possible data issue. Contact StoreConnect Support with the error details.

Troubleshooting quick reference

Symptom	Likely cause	Resolution
POS shows login screen unexpectedly	Local Storage cleared or session expired	Re-login. IndexedDB data is intact, so no data wipe is needed.
“Initializing” spinner on load	Schema migration in progress after an upgrade	Wait for it to complete. Do not refresh or close the browser. Check logs if it persists.
Missing records during an initial sync	The initial sync downloads most records newest first but orders and order fulfillments oldest first, so older records, or today’s orders, may not have arrived yet	Allow time for the sync to work through the backlog. Check progress under Settings then Manage data.
Missing records after re-login	The register is catching up on changes made while it was offline	Records populate progressively. Give it time.
POS is slow or unresponsive during sync	Initial sync or large delta sync in progress	Allow the sync to complete. Avoid running other heavy applications on the device during sync.
A record deleted at another register still shows	The delete has not reached this register yet	Wait for the next check, normally within a minute. If this register was offline, it receives the delete when it reconnects.
A record deleted in Salesforce still shows	StoreConnect processes Salesforce deletions every 10 minutes	Allow 10 to 15 minutes.
Persistent errors after reconnecting	Possible data corruption or schema mismatch	Contact StoreConnect Support. A data wipe may be advised as a last resort.
A custom field or object does not appear on the register	A Custom Data Mapping exists but no POS Layout Field does	Add the POS Layout and its layout fields, then boot the app. A mapping alone does not sync a field to the device.
A newly added object still has no data after a resync	Its table is created on boot, and a sync cannot create one	Refresh the browser, or close and reopen the native app.
Schema does not rebuild on refresh	Another tab holds the local database open	Close every other POS tab and window on the device, then reload.
“We couldn’t load your register” with “Failed while: Opening database”	Another POS tab, window, or browser process holds the local database open	Close every other POS tab and window on the device and select Refresh. If it returns, quit the browser fully and reopen. Use Reset register only after that; it wipes unsynced data. See Troubleshoot a frozen or crashed POS.
A value saved from a custom view is not in Salesforce	The change is queued locally and has not uploaded	Check Unsaved records for that object under Settings then Manage data.

Device and environment recommendations

• Use modern hardware. Sync performance is heavily influenced by device CPU and storage speed. See Compatible hardware for POS for recommended devices.
• Use a supported, up-to-date browser. POS relies on modern browser APIs. Keep the browser updated to the latest stable version.
• Maintain a stable network connection. While POS is resilient to intermittent connectivity, a stable connection ensures delta syncs stay current.
• Avoid clearing site data routinely. There is no benefit to periodically clearing browser data for POS — it will only trigger unnecessary re-syncs.
• Avoid browser extensions that aggressively manage storage. Some privacy or performance extensions may interfere with IndexedDB or Local Storage. Whitelist the POS URL if necessary.
• Keep the POS tab active during initial sync. Browsers may throttle background tabs, which can slow down the database build process.
• Bookmark the POS URL. A bookmarked URL ensures consistency and avoids navigating to incorrect addresses.