Skip to main content
Version: 1.x

Connecting to Your Store

Desktop & Mobile Only

This screen is only shown in the Desktop and Mobile apps. Web users access the POS directly at yourdomain.com/pos and log in with their WordPress credentials.

Connect Screen Overview​

When you open the WCPOS Desktop or Mobile app, you'll see the Connect screen. This is where you manage your store connections and user logins.

Adding a New Store​

  1. Enter your WooCommerce store URL in the text field (e.g., https://mystore.com)
  2. Click Connect
  3. You'll be redirected to log in with your WordPress credentials
  4. After successful login, you'll be returned to the app

Multiple Stores​

You can connect to as many WooCommerce stores as you need. Each store appears as a separate card on the Connect screen, showing:

  • Store name and favicon
  • Store URL
  • Logged in users for that store

This is useful if you manage multiple locations or businesses.

Multiple Users Per Store​

Each store can have multiple users logged in simultaneously. This is helpful for:

  • Shift changes - New cashier can log in before the previous one logs out
  • Multi-register setups - Different cashiers on different devices
  • Quick switching - Easily switch between user accounts

Adding a User​

Click the button next to "Logged in users" to add another user to that store.

Switching Users​

Click on a user badge (e.g., "Brenda") to open the POS as that user.

Removing a User​

Click the × on a user badge to log that user out of the store.

Removing a Store​

Click the red × button on the store card to remove it from your list. This logs out all users and removes the store connection from the app.

Demo Store​

At the bottom of the screen, you may see an "Enter Demo Store" link. This connects you to a demo WooCommerce store to try out WCPOS features without affecting your own store data.

Troubleshooting​

First thing to check: X-Frame-Options

The desktop and mobile apps use iframes for login, payment, and receipts. Any server header or plugin that sends X-Frame-Options: DENY or SAMEORIGIN will break login. This is the single most common cause of app login failures — check the login page's response headers (browser dev tools, or curl -I https://yourstore.com/wp-login.php) before anything else.

Can't connect to my store?
  • Ensure the WCPOS plugin is installed and activated on your WordPress site
  • Check that you're using the correct URL (include https:// — the WooCommerce REST API requires SSL)
  • Try opening yourdomain.com/pos in a web browser first to confirm the plugin works
  • Verify that the WooCommerce REST API is accessible
  • Check that your user account has POS access permissions
Login fails in the desktop or mobile app

Most app login failures are caused by a security or caching plugin blocking the login iframe:

  • X-Frame-Options headers (set by a security plugin or your server) block the login iframe — see the note above. Temporarily disable the security plugin, log in, then re-enable it (your session lasts about a week).
  • Security plugins — Wordfence, Really Simple Security, WPS Hide Login, iThemes/Solid Security, and Defender Pro are common culprits. See the full list and fixes in Plugin Conflicts.
  • Wordfence 2FA — the 2FA code field doesn't render in the login iframe. Disable 2FA for POS users for now.
  • Custom login URL (e.g. WPS Hide Login) — the app can't find the login page. Use the standard /wp-admin/ URL.
  • Caching plugins can keep serving the blocked login form even after you disable the offending plugin — clear the cache, or clear the app cache / reinstall the desktop app.
"REST API requires authentication" or a security-plugin error on the connect screen

A plugin (e.g. Force Login or a JWT auth plugin) is requiring authentication for all REST API requests, so the app can't read your site's public info. The app now shows the server's actual message (e.g. "Only authenticated users can access the REST API") instead of misreporting the site type.

Fix: configure the security plugin to allow unauthenticated access to /wp-json/wcpos/ and /wp-json/wc/v3/, or disable it just long enough to complete the first connection.

"Does not appear to be a WordPress site" (desktop app)

The desktop app discovers the REST API via the HTTP Link header. If a plugin (commonly Image Prioritizer or other performance plugins) floods or truncates that header, discovery fails. Fix: disable image-optimisation / header-modifying performance plugins and retry.

The app says it needs an update / crashes after an update

Check for a version mismatch between the app and the server plugin — the app store may have pushed an app update while the WCPOS plugin still needs updating (or vice-versa). Make sure the app and the WCPOS plugin are on the same major version. WCPOS v1.9.0+ apps require the WCPOS plugin to be v1.8.0 or higher.

"Cannot create fast store database" error

This is a race condition on first login. Close the app completely and try again — it usually succeeds on the second attempt.

Stuck on the user-selection screen (desktop app)

After logging in you see your username but no obvious way forward. Click your username/name to proceed into the POS — the name itself is the button.

Connection keeps failing?
  • Try accessing yourdomain.com/pos in a web browser first to verify the plugin is working
  • Check your site's error logs for any issues
  • Confirm your host isn't blocking the REST API — see Hosting-Specific Notes
  • Ensure your server meets the minimum requirements