WooCommerce POS Troubleshooting

Most POS problems trace back to a handful of causes: stale permalinks, a blocked REST API, an offline register, or a configuration that does not match the workflow. Work through the scenario that matches your symptom, or look your exact message up in the error message index.

If nothing here resolves the issue, follow the pre-ticket checklist so support can help you quickly.

First Checks

Before deeper digging, rule out the three most common causes:

Flush permalinks. Go to Settings → Permalinks in WordPress admin and click Save Changes. Stale rewrite rules are the top cause of POS pages that 404 or redirect.
Confirm the REST API is reachable. The register communicates with WordPress through the REST API. Open https://your-site.com/wp-json/ in a browser — it should return JSON, not an error page or a security challenge.
Check the connection state. An offline register deliberately disables some actions (coupons, customer edits). Reconnect, then retry.

Troubleshooting Scenarios

The POS page will not open, shows 404, or redirects to My Account

Work through these steps in order:

1. Flush permalinks from Settings → Permalinks → Save Changes.
2. Confirm you are logging in with a POS user account, not a regular customer or admin account — the POS route only opens for assigned POS users. Create or check the account under Point of Sale → POS Users.
3. Confirm the POS user is assigned to an outlet — an unassigned user sees "Outlet is not assigned!". Assign the outlet from Outlets & POS Users.
4. If the page is blank, check for a security plugin or firewall blocking /wp-json/ — see hosting conflicts.

Offline orders are not syncing back to WooCommerce

1. Click the offline sync button in the POS panel to trigger a manual sync — "No offline order to Sync" means everything already reached WooCommerce.
2. Enable Auto Sync Offline Orders in the POS settings so orders sync automatically once the register is back online.
3. Confirm the outlet uses Master Stock inventory — offline selling does not work with Centralized Stock ("Cannot process orders with centralized inventory at offline mode").
See offline orders for the full workflow.

A coupon will not apply at the register

1. Make sure the register is online — coupons cannot be applied in offline mode.
2. Read the exact message shown: WooCommerce coupon restrictions (minimum spend, product limits, usage limits, expiry) are enforced at the POS, and the register displays the same message the online store would — for example, "The minimum spend for coupon "X" is $50.00."
3. "Invalid coupon code" can also appear when the register session has expired — log out of the POS and log back in, then retry.
See checkout discounts and coupons.

Receipts will not print, or print in the wrong format

1. Check the printer type configured in Invoice Printer settings — A3, A4, A5, A6 and the Epson TM-T88V thermal printer are supported, and the layout follows the selected type.
2. Confirm invoice printing (and auto-print, if wanted) is enabled for POS users.
3. Confirm the printer's drivers work outside the browser first, then test a print from the register.
See invoice printer support.

The desktop app cannot connect to the store

The desktop app pairs with your store using the App Connection Password from the POS General Configurations. "Invalid app connection password" means the entered password does not match — generate a new password from the settings screen and pair again. See initial configuration.

Stock numbers look wrong between the store and the POS

1. Stock updates automatically when an order status changes — confirm the order actually changed status.
2. Review which inventory model the outlet uses (Master Stock keeps separate POS stock; Centralized Stock shares the WooCommerce stock) in Master Stock management.
3. Sync any pending offline orders — unsynced sales have not reached WooCommerce yet.

Error Message Index

The exact wording shown at the register, what it means, and what to do.

Message	Meaning	Fix
Outlet is not assigned!	The POS user has no outlet mapped	Assign the user to an outlet under Outlets & POS Users
Invalid coupon code	The code does not match an active coupon, or the register session has expired	Check the code in Marketing → Coupons; re-log in to the POS if the code is definitely valid
Coupon cannot be applied on offline mode	Coupons need a live connection for validation	Reconnect and retry, or apply a manual discount instead
Cannot process orders with centralized inventory at offline mode.	Offline selling requires Master Stock inventory	Switch the inventory type, or reconnect before checking out
Cannot add, edit, delete customer in offline mode	Customer accounts need a live connection	Sell to the default customer offline and update details later
Invalid app connection password.	The desktop app pairing password is wrong	Generate a new App Connection Password in POS General Configurations
Drawer session not found.	No open drawer session for the action	Open the drawer with an opening amount before drawer operations
Entered amount cannot be paid	The tendered amount does not cover the payable total	Enter an amount equal to or above the payable amount
Discount cannot be applied due to invalid total amount	The discount does not fit the current cart total	Check the discount value against the cart total
The minimum spend for coupon "X" is $Y.	A WooCommerce coupon restriction is not met	Meet the restriction or remove it from the coupon in WooCommerce
No offline order to Sync	Informational — nothing is waiting to sync	No action needed

Hosting, Cache and Firewall Conflicts

The register is a browser application that talks to WordPress over the REST API (/wp-json/pos/v1/...). Anything that blocks, challenges, or caches those requests breaks the POS:

Security plugins and WAF rules that restrict the REST API must allow the /wp-json/ routes for logged-in POS users.
Cloudflare and similar firewalls should not present browser challenges on /wp-json/ requests or the POS endpoint — exclude them from bot-fight or challenge rules.
Page caching must never cache the POS endpoint or /wp-json/ responses — exclude both from any full-page or CDN cache.
Aggressive JavaScript optimization (merging or deferring scripts) can break the register app — exclude the POS endpoint from asset optimization.

After changing hosting or firewall rules, reload the register and confirm https://your-site.com/wp-json/ returns JSON in the browser.

Logs and Debugging

When a problem is not covered above, collect evidence before changing anything:

Browser console — open the register, press F12, and check the Console and Network tabs for failing (red) requests to /wp-json/pos/v1/..., including their HTTP status codes.
WooCommerce logs — check WooCommerce → Status → Logs for fatal errors around the time of the issue.
WordPress debug log — with WP_DEBUG and WP_DEBUG_LOG enabled in wp-config.php, PHP errors are written to wp-content/debug.log.
Conflict test — if the issue started after installing another plugin, temporarily deactivate it on a staging site and retest.

These are exactly the details worth attaching to a support ticket — see Before You Open a Ticket.

REST API and Integrations

The register communicates with WordPress through REST routes under the pos/v1 namespace — the REST API must stay enabled and reachable for the POS to work.
Pretty permalinks are required for the POS routes; flush them after installation or migration.
Payment terminals (Stripe, Square, PayPal, Linkly, Stripe Reader M2) connect through separate add-on plugins — see Payment Terminal Integrations for the list and how they attach to the register.
For a custom mobile app or deeper integration work, contact the Webkul team at [email protected].

FAQ & Notes — compatibility, limitations, and version information.
Before You Open a Ticket — the checklist that speeds up support.
POS Help Center — all help topics in one place.