WooCommerce POS DocumentationWooCommerce POS Documentation
Buy Now
View Demo
Changelog
  • WooCommerce POS

    • Point Of Sale
    • Overview
    • Features
    • Help Center
    • POS Comparison
    • Installation
    • Admin Configuration
    • Outlets & Users
    • Bulk Assignment
    • Dynamic Theme
    • Notification Tones
    • Variation Layouts
    • Cart Totals & Editing
    • Products & Inventory
    • Stock Visibility
    • Out of Stock Products
    • ATUM Inventory Management
    • Per-Outlet Pricing
    • Orders & Drawers
    • Checkout Discounts & Coupons
    • Checkout Fees
    • Z-Report
    • Cash Management
    • Hold Cart
    • Custom Products
    • Hardware Support
    • Direct Printing
    • Cash Drawer
    • Payment Terminal
    • Payment Integration
    • WhatsApp Notification
    • Multisite Compatibility
    • Reports & Analytics
    • POS Agent Guide
    • Desktop & Mobile
    • FAQ & Notes
    • Troubleshooting
  • Core POS System

    • WooCommerce POS Outlet Manager
    • WooCommerce POS Warehouse Management
  • Mobile Apps

    • WooCommerce Flutter Native POS Mobile App
  • Printer Integrations

    • WooCommerce POS Cloud Printer
  • Payment Terminal Integrations

    • WooCommerce Stripe POS Terminal Connector
    • WooCommerce POS Square Payment Terminal Plugin
    • WooCommerce POS PayPal Terminal Reader
    • WooCommerce POS Linkly Terminal Connector
    • WooCommerce POS Stripe Reader M2 Integration
  • Order & Transaction Management

    • POS Order Return & Exchange for WooCommerce
    • WooCommerce POS Partial Payment Plugin
    • POS Booking Reservation Plugin for WooCommerce
    • WooCommerce POS Multicurrency
  • Customer & Loyalty Features

    • WooCommerce & POS Loyalty Management
    • WooCommerce POS Gift Card Plugin
    • WooCommerce POS Happy Hours
    • WooCommerce POS Complimentary Goods
  • Hardware & Barcode Solutions

    • WooCommerce POS Configurable Barcode
    • WooCommerce POS Barcode RFGun
    • WooCommerce POS RFID Card Add-on
    • WooCommerce POS Cloud Printer Add-on
  • Customer Interface & Kiosk

    • WooCommerce POS Customer Kiosk Checkout
    • WooCommerce POS Customer Cart Screen
    • WooCommerce POS QR Code Ordering System
  • Industry-Specific Solutions

    • WooCommerce Restaurant Kitchen POS
    • Delivery Management Addon for WooCommerce POS
  • Advanced Features

    • POS AI Reporting for WooCommerce
Buy Now
View Demo
Changelog
  • WooCommerce POS

    • Point Of Sale
    • Overview
    • Features
    • Help Center
    • POS Comparison
    • Installation
    • Admin Configuration
    • Outlets & Users
    • Bulk Assignment
    • Dynamic Theme
    • Notification Tones
    • Variation Layouts
    • Cart Totals & Editing
    • Products & Inventory
    • Stock Visibility
    • Out of Stock Products
    • ATUM Inventory Management
    • Per-Outlet Pricing
    • Orders & Drawers
    • Checkout Discounts & Coupons
    • Checkout Fees
    • Z-Report
    • Cash Management
    • Hold Cart
    • Custom Products
    • Hardware Support
    • Direct Printing
    • Cash Drawer
    • Payment Terminal
    • Payment Integration
    • WhatsApp Notification
    • Multisite Compatibility
    • Reports & Analytics
    • POS Agent Guide
    • Desktop & Mobile
    • FAQ & Notes
    • Troubleshooting
  • Core POS System

    • WooCommerce POS Outlet Manager
    • WooCommerce POS Warehouse Management
  • Mobile Apps

    • WooCommerce Flutter Native POS Mobile App
  • Printer Integrations

    • WooCommerce POS Cloud Printer
  • Payment Terminal Integrations

    • WooCommerce Stripe POS Terminal Connector
    • WooCommerce POS Square Payment Terminal Plugin
    • WooCommerce POS PayPal Terminal Reader
    • WooCommerce POS Linkly Terminal Connector
    • WooCommerce POS Stripe Reader M2 Integration
  • Order & Transaction Management

    • POS Order Return & Exchange for WooCommerce
    • WooCommerce POS Partial Payment Plugin
    • POS Booking Reservation Plugin for WooCommerce
    • WooCommerce POS Multicurrency
  • Customer & Loyalty Features

    • WooCommerce & POS Loyalty Management
    • WooCommerce POS Gift Card Plugin
    • WooCommerce POS Happy Hours
    • WooCommerce POS Complimentary Goods
  • Hardware & Barcode Solutions

    • WooCommerce POS Configurable Barcode
    • WooCommerce POS Barcode RFGun
    • WooCommerce POS RFID Card Add-on
    • WooCommerce POS Cloud Printer Add-on
  • Customer Interface & Kiosk

    • WooCommerce POS Customer Kiosk Checkout
    • WooCommerce POS Customer Cart Screen
    • WooCommerce POS QR Code Ordering System
  • Industry-Specific Solutions

    • WooCommerce Restaurant Kitchen POS
    • Delivery Management Addon for WooCommerce POS
  • Advanced Features

    • POS AI Reporting for WooCommerce
  • Getting Started

    • WooCommerce Point of Sale (POS)
    • Overview
    • Features
    • WooCommerce POS Comparison
    • Installation
  • Setup & Configuration

    • Admin Configuration
    • Outlets & POS Users
    • Bulk Assignment
    • Dynamic Theme in WooCommerce Point of Sale
    • Notification Tones
    • Variation Card Layouts
    • Cart Totals & Item Editing
  • Store Operations

    • WooCommerce Point of Sale – Products & Inventory Management
    • Stock Visibility Controls
    • Out of Stock Products
    • ATUM Inventory Management
    • Per-Outlet Pricing
    • Orders & Cash Drawer
    • Checkout Discounts & Coupons
    • Checkout Fees
    • WooCommerce POS - Cashier Management
    • WooCommerce POS - Hold Cart
    • Z-Report Generation & Printing
    • WooCommerce POS - Custom Product
  • Hardware Integrations

    • WooCommerce POS - Hardware Support
    • Direct Printing
    • WooCommerce POS – Cash Drawer & Cashier Management
    • WooCommerce POS – Payment Methods & Checkout Configuration
    • WooCommerce POS – Payment Terminal Integration
  • Advanced Features

    • WhatsApp Notifications in WooCommerce Point of Sale
    • WooCommerce POS - Multisite Compatibility
    • Reports & Analytics
    • POS Agent Guide
    • Desktop & Mobile POS
  • Help & FAQ

    • POS Help Center
    • FAQ & Notes
    • Troubleshooting
    • Before You Open a Ticket

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:

  1. 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.
  2. 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.
  3. 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 → 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 POS Invoice Option is enabled in the General settings — without it, POS users get no option to print the invoice.
3. For the Epson TM-T88V thermal page, check Thermal Roll Width (mm) and Thermal Roll Height (mm) match your paper roll.
4. Confirm the printer's drivers work outside the browser first, then test a print from the register.
If you print through the print service instead of the browser dialog, see the direct printing scenario below and Direct Printing.
See invoice printer support.

Direct printing does not reach the printer

These checks apply when Print service is enabled under Point of Sale → Settings → Printing. See Direct Printing for the full setup.

1. "The print service API key is wrong or has been revoked." — the key no longer works. Create a new key in your print service account, paste it into API key and save.
2. "The print service has no prints left for this period." — your print service account has used up its prints for the current period. Check the account with the print service; until prints are available again, print from the browser dialog.
3. "That printer is no longer on your account, so it was not saved. Refresh the printer list and pick again." — the printer was removed from the print service account. Click Refresh printers and choose a printer that is still listed. Offline printers show their status after the name.
4. The browser print dialog opens instead of printing directly — receipts and drawer reports go through the print service only when the till's invoice page size is Epson TM-T88V Thermal Page. With any other page size, or when the print service cannot print the job, the register falls back to the browser print dialog. Also check which thermal printer is in use: a printer picked for the session from the printer icon in the POS header comes first, then the outlet's Thermal printer, then the store-wide Thermal printer.
5. "This barcode is too long for the label width set under Printing settings." or "The label height set under Printing settings is too small for a barcode." — increase Label width (dots) or Label height (dots) in the ZPL printer section to match your labels (203 dpi, so 8 dots ≈ 1 mm).
6. "No ZPL printer has been chosen. Pick one under POS Settings > Printing first." — choose a printer in the ZPL printer section and save before printing barcode labels from Point of Sale → Products.
7. A job sits waiting — the print service desktop app on the till computer must be running. Jobs wait instead of failing while that computer is asleep, and print once it is back.

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.
4. If you use ATUM Inventory Management with Centralized Stock, the register shows only the stock above ATUM's out-of-stock threshold, so it can be lower than WooCommerce's quantity. See ATUM Inventory Management.

POS order emails are late or are not sent

1. Confirm Enable Mails at POS end is enabled in the POS Panel Configurations — when disabled, no emails are sent for POS orders.
2. From version 7.4.0, POS order emails are sent in the background a few moments after the sale. Open WooCommerce → Status → Scheduled Actions and look in the woocommerce-emails group. Pending actions that never complete mean WordPress scheduled tasks are not running on your site. Ask your host to make sure WP-Cron, or a real server cron job, runs regularly.
3. If the actions complete but no email arrives, check your site's mail sending with an SMTP plugin, as you would for any WooCommerce email.
See order emails.


Error Message Index

The exact wording shown at the register or in the POS settings, what it means, and what to do.

MessageMeaningFix
Outlet is not assigned!The POS user has no outlet mappedAssign the user to an outlet under Outlets & POS Users
Invalid coupon codeThe code does not match an active coupon, or the register session has expiredCheck the code in Marketing → Coupons; re-log in to the POS if the code is definitely valid
Coupon cannot be applied on offline modeCoupons need a live connection for validationReconnect and retry, or apply a manual discount instead
Cannot process orders with centralized inventory at offline mode.Offline selling requires Master Stock inventorySwitch the inventory type, or reconnect before checking out
Cannot add, edit, delete customer in offline modeCustomer accounts need a live connectionSell to the default customer offline and update details later
Invalid app connection password.The desktop app pairing password is wrongGenerate a new App Connection Password in POS General Configurations
Drawer session not found.No open drawer session for the actionOpen the drawer with an opening amount before drawer operations
Entered amount cannot be paidThe tendered amount does not cover the payable totalEnter an amount equal to or above the payable amount
Discount cannot be applied due to invalid total amountThe discount does not fit the current cart totalCheck the discount value against the cart total
The minimum spend for coupon "X" is $Y.A WooCommerce coupon restriction is not metMeet the restriction or remove it from the coupon in WooCommerce
No offline order to SyncInformational — nothing is waiting to syncNo action needed
Not enough stock for: Product (available: N). Please update the cart and try again.With ATUM and Centralized Stock, current stock no longer covers the cart, for example after a website saleReduce the quantity or remove the listed products, then pay again — see ATUM Inventory Management
The print service API key is wrong or has been revoked.Direct printing cannot sign in to the print serviceCreate a new API key and save it under Point of Sale → Settings → Printing
The print service has no prints left for this period.The print service account has used up its prints for the periodCheck your print service account; print from the browser dialog meanwhile
Too many print requests. Please try again shortly.The print service is limiting requestsWait a moment and print again
That printer is no longer on your account, so it was not saved. Refresh the printer list and pick again.The chosen printer was removed from the print service accountClick Refresh printers and choose a listed printer
This barcode is too long for the label width set under Printing settings.The barcode does not fit the ZPL label widthIncrease Label width (dots) under Printing → ZPL printer
The label height set under Printing settings is too small for a barcode.The ZPL label is too short for the barcodeIncrease Label height (dots) under Printing → ZPL printer
No ZPL printer has been chosen. Pick one under POS Settings > Printing first.Barcode labels need a ZPL printerChoose a ZPL printer under Point of Sale → Settings → Printing and save

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:

  1. 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.
  2. WooCommerce logs — check WooCommerce → Status → Logs for fatal errors around the time of the issue.
  3. WordPress debug log — with WP_DEBUG and WP_DEBUG_LOG enabled in wp-config.php, PHP errors are written to wp-content/debug.log.
  4. 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].

Related Pages

  • 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.
Prev
FAQ & Notes
Next
Before You Open a Ticket