# WCPOS Documentation > WCPOS is a free, open-source Point of Sale (POS) application for WooCommerce. It turns any WooCommerce-powered online store into a fully-featured retail POS system. - [WCPOS Documentation](/index.md) ## category ### developer-reference - [Developer Reference](/category/developer-reference.md) ### managing-your-store - [Managing Your Store](/category/managing-your-store.md) ### troubleshooting - [Troubleshooting](/category/troubleshooting.md) ## coupons Manage and apply WooCommerce coupons in WCPOS, including creating coupons, validation rules, and applying them at the register. - [Coupons](/coupons.md): Manage and apply WooCommerce coupons in WCPOS, including creating coupons, validation rules, and applying them at the register. ### applying-coupons The cashier workflow for applying WooCommerce coupons at the WCPOS register — search, coupon pills, sequential discounts, and resolving validation errors. - [Applying Coupons at the Till](/coupons/applying-coupons.md): The cashier workflow for applying WooCommerce coupons at the WCPOS register — search, coupon pills, sequential discounts, and resolving validation errors. ## customers Manage WooCommerce customers in WCPOS, including customer lookup, editing details, and viewing order history. - [Customers](/customers.md): Manage WooCommerce customers in WCPOS, including customer lookup, editing details, and viewing order history. ## error-codes Reference guide for WCPOS error codes, including API, database, payment, and system errors with troubleshooting steps. - [Error Codes](/error-codes.md): Reference guide for WCPOS error codes, including API, database, payment, and system errors with troubleshooting steps. ### api API errors occur when communicating with your WooCommerce server. These errors are prefixed with API and are organized into the following categories: - [API Errors](/error-codes/api.md): API errors occur when communicating with your WooCommerce server. These errors are prefixed with API and are organized into the following categories: ### API01001 What This Means - [API01001: Connection Timeout](/error-codes/API01001.md): What This Means ### API01002 What This Means - [API01002: Connection Refused](/error-codes/API01002.md): What This Means ### API01003 What This Means - [API01003: Connection Reset](/error-codes/API01003.md): What This Means ### API01004 What This Means - [API01004: DNS Resolution Failed](/error-codes/API01004.md): What This Means ### API01005 What This Means - [API01005: SSL Certificate Error](/error-codes/API01005.md): What This Means ### API01006 What This Means - [API01006: Network Unreachable](/error-codes/API01006.md): What This Means ### API01007 What This Means - [API01007: Device Offline](/error-codes/API01007.md): What This Means ### API01008 What This Means - [API01008: Website Unavailable](/error-codes/API01008.md): What This Means ### API02001 What This Means - [API02001: Invalid Credentials](/error-codes/API02001.md): What This Means ### API02002 What This Means - [API02002: Token Expired](/error-codes/API02002.md): What This Means ### API02003 What This Means - [API02003: Token Invalid](/error-codes/API02003.md): What This Means ### API02004 What This Means - [API02004: User Not Authorized](/error-codes/API02004.md): What This Means ### API02005 What This Means - [API02005: Insufficient Permissions](/error-codes/API02005.md): What This Means ### API02006 What This Means - [API02006: API Key Invalid](/error-codes/API02006.md): What This Means ### API02007 What This Means - [API02007: Token Refresh Failed](/error-codes/API02007.md): What This Means ### API02008 What This Means - [API02008: Refresh Token Invalid](/error-codes/API02008.md): What This Means ### API02009 What This Means - [API02009: Refresh Token Expired](/error-codes/API02009.md): What This Means ### API02010 What This Means - [API02010: Auth Required](/error-codes/API02010.md): What This Means ### API03001 What This Means - [API03001: Invalid Request Format](/error-codes/API03001.md): What This Means ### API03002 What This Means - [API03002: Missing Required Parameters](/error-codes/API03002.md): What This Means ### API03003 What This Means - [API03003: Invalid Parameter Value](/error-codes/API03003.md): What This Means ### API03004 What This Means - [API03004: Request Too Large](/error-codes/API03004.md): What This Means ### API03005 What This Means - [API03005: Rate Limit Exceeded](/error-codes/API03005.md): What This Means ### API03006 What This Means - [API03006: Unsupported Method](/error-codes/API03006.md): What This Means ### API03007 What This Means - [API03007: Request Queue Full](/error-codes/API03007.md): What This Means ### API04001 What This Means - [API04001: Invalid Response Format](/error-codes/API04001.md): What This Means ### API04002 What This Means - [API04002: Unexpected Response Code](/error-codes/API04002.md): What This Means ### API04003 What This Means - [API04003: Malformed JSON Response](/error-codes/API04003.md): What This Means ### API04004 What This Means - [API04004: Missing Response Data](/error-codes/API04004.md): What This Means ### API04005 What This Means - [API04005: JSON Recovery Attempted](/error-codes/API04005.md): What This Means ### API04006 What This Means - [API04006: Resource Not Found](/error-codes/API04006.md): What This Means ### API05001 What This Means - [API05001: WooCommerce API Disabled](/error-codes/API05001.md): What This Means ### API05002 What This Means - [API05002: WCPOS Plugin Not Found](/error-codes/API05002.md): What This Means ### API05003 What This Means - [API05003: WCPOS Plugin Outdated](/error-codes/API05003.md): What This Means ### API05004 What This Means - [API05004: WordPress API Disabled](/error-codes/API05004.md): What This Means ### API05005 What This Means - [API05005: Plugin Not Found](/error-codes/API05005.md): What This Means ### API06001 What This Means - [API06001: Invalid URL Format](/error-codes/API06001.md): What This Means ### API06002 What This Means - [API06002: Missing API URL](/error-codes/API06002.md): What This Means ### API06003 What This Means - [API06003: Invalid Site Configuration](/error-codes/API06003.md): What This Means ### db Database errors occur when storing or retrieving data in the local database. WCPOS uses a local database to store products, customers, and other data for fast access and offline functionality. These errors are prefixed with DB. - [Database Errors](/error-codes/db.md): Database errors occur when storing or retrieving data in the local database. WCPOS uses a local database to store products, customers, and other data for fast access and offline functionality. These errors are prefixed with DB. ### DB01001 What This Means - [DB01001: Connection Failed](/error-codes/DB01001.md): What This Means ### DB01002 What This Means - [DB01002: Query Timeout](/error-codes/DB01002.md): What This Means ### DB01003 What This Means - [DB01003: Transaction Failed](/error-codes/DB01003.md): What This Means ### DB02001 What This Means - [DB02001: Duplicate Record](/error-codes/DB02001.md): What This Means ### DB02002 What This Means - [DB02002: Record Not Found](/error-codes/DB02002.md): What This Means ### DB02003 What This Means - [DB02003: Constraint Violation](/error-codes/DB02003.md): What This Means ### DB03001 What This Means - [DB03001: Query Syntax Error](/error-codes/DB03001.md): What This Means ### DB03002 What This Means - [DB03002: Invalid Data Type](/error-codes/DB03002.md): What This Means ### DB03003 What This Means - [DB03003: Missing Required Field](/error-codes/DB03003.md): What This Means ### py Payment errors occur during checkout and payment processing. These errors are prefixed with PY and relate to issues with payment cards, gateways, and transactions. - [Payment Errors](/error-codes/py.md): Payment errors occur during checkout and payment processing. These errors are prefixed with PY and relate to issues with payment cards, gateways, and transactions. ### PY01001 What This Means - [PY01001: Payment Declined](/error-codes/PY01001.md): What This Means ### PY01002 What This Means - [PY01002: Insufficient Funds](/error-codes/PY01002.md): What This Means ### PY01003 What This Means - [PY01003: Card Expired](/error-codes/PY01003.md): What This Means ### PY01004 What This Means - [PY01004: Invalid Card Number](/error-codes/PY01004.md): What This Means ### PY02001 What This Means - [PY02001: Payment Gateway Error](/error-codes/PY02001.md): What This Means ### PY02002 What This Means - [PY02002: Payment Timeout](/error-codes/PY02002.md): What This Means ### sy System errors are related to device resources and system configuration. These errors are prefixed with SY and indicate issues with your device or the POS application itself. - [System Errors](/error-codes/sy.md): System errors are related to device resources and system configuration. These errors are prefixed with SY and indicate issues with your device or the POS application itself. ### SY01001 What This Means - [SY01001: Out of Memory](/error-codes/SY01001.md): What This Means ### SY01002 What This Means - [SY01002: Disk Full](/error-codes/SY01002.md): What This Means ### SY01003 What This Means - [SY01003: Permission Denied](/error-codes/SY01003.md): What This Means ### SY02001 What This Means - [SY02001: Invalid Configuration](/error-codes/SY02001.md): What This Means ### SY02002 What This Means - [SY02002: Service Unavailable](/error-codes/SY02002.md): What This Means ## extensions Browse, install, and manage POS extensions from the extension directory. Learn how to create and submit your own extensions. - [Extensions](/extensions.md): Browse, install, and manage POS extensions from the extension directory. Learn how to create and submit your own extensions. ### atum Link WCPOS Pro stores to ATUM Multi-Inventory locations for per-location stock, pricing, and SKUs at the POS. - [WCPOS ATUM Integration](/extensions/atum.md): Link WCPOS Pro stores to ATUM Multi-Inventory locations for per-location stock, pricing, and SKUs at the POS. ### polylang Filter WCPOS products by Polylang language and avoid duplicate translated products in the POS. - [WCPOS Polylang](/extensions/polylang.md): Filter WCPOS products by Polylang language and avoid duplicate translated products in the POS. ### storeapps-smart-coupons StoreApps Smart Coupons store credit compatibility for WCPOS receipts, order notes, and POS balance deductions. - [WCPOS StoreApps Smart Coupons](/extensions/storeapps-smart-coupons.md): StoreApps Smart Coupons store credit compatibility for WCPOS receipts, order notes, and POS balance deductions. ### wp-multilang Filter WCPOS products by WP Multilang language and avoid duplicate translated products in the POS. - [WCPOS WP Multilang](/extensions/wp-multilang.md): Filter WCPOS products by WP Multilang language and avoid duplicate translated products in the POS. ### wpml Filter WCPOS products by WPML language and avoid duplicate translated products in the POS. - [WCPOS WPML](/extensions/wpml.md): Filter WCPOS products by WPML language and avoid duplicate translated products in the POS. ## getting-started ### connect How to connect WCPOS to your WooCommerce store, including login options and troubleshooting connection issues. - [Connecting to Your Store](/getting-started/connect.md): How to connect WCPOS to your WooCommerce store, including login options and troubleshooting connection issues. ### free-vs-pro A side-by-side comparison of WCPOS Free and WCPOS Pro — every feature, payment gateway, and capability so you can decide which one you need. - [Free vs Pro](/getting-started/free-vs-pro.md): A side-by-side comparison of WCPOS Free and WCPOS Pro — every feature, payment gateway, and capability so you can decide which one you need. ### installation Minimum requirements for WCPOS including WordPress, WooCommerce, and PHP versions, supported browsers, and minimum desktop and mobile operating system versions. - [Installation Requirements](/getting-started/installation.md): Minimum requirements for WCPOS including WordPress, WooCommerce, and PHP versions, supported browsers, and minimum desktop and mobile operating system versions. ### offline What works offline in WCPOS, how the local database syncs with WooCommerce, and what happens when connectivity is lost. - [Offline Functionality](/getting-started/offline.md): What works offline in WCPOS, how the local database syncs with WooCommerce, and what happens when connectivity is lost. ### previous-versions How to downgrade WCPOS by installing a previous version of the plugin from WordPress.org. - [Re-Installing a Previous Version of the WCPOS Plugin](/getting-started/previous-versions.md): How to downgrade WCPOS by installing a previous version of the plugin from WordPress.org. ### pro-license If you have purchased the Pro version please follow the steps below to install the plugin. - [Installing WCPOS Pro](/getting-started/pro-license.md): If you have purchased the Pro version please follow the steps below to install the plugin. ### roadmap Where WCPOS is headed — the public roadmap, how to request or vote on features, and the major themes in development. - [Roadmap](/getting-started/roadmap.md): Where WCPOS is headed — the public roadmap, how to request or vote on features, and the major themes in development. ## hardware Connect physical devices to WCPOS — receipt printers, barcode scanners, card readers, and cash drawers. - [Hardware](/hardware.md): Connect physical devices to WCPOS — receipt printers, barcode scanners, card readers, and cash drawers. ### printers Connect a receipt printer to WCPOS — over the network, Bluetooth, or USB, on the web, desktop, and mobile apps. - [Printer Setup](/hardware/printers.md): Connect a receipt printer to WCPOS — over the network, Bluetooth, or USB, on the web, desktop, and mobile apps. ## orders View and manage WooCommerce orders in WCPOS, including order history, refunds, and reprinting receipts. - [Orders](/orders.md): View and manage WooCommerce orders in WCPOS, including order history, refunds, and reprinting receipts. ### refunds Issue full or partial refunds for WooCommerce orders directly from WCPOS, with support for refunds back to the original payment method or out of the till as cash. - [Refunds](/orders/refunds.md): Issue full or partial refunds for WooCommerce orders directly from WCPOS, with support for refunds back to the original payment method or out of the till as cash. ## payment Configure payment methods in WCPOS including cash, card, and custom payment gateways like Stripe Terminal and SumUp. - [Payment Methods](/payment.md): Configure payment methods in WCPOS including cash, card, and custom payment gateways like Stripe Terminal and SumUp. ### gateways Payment gateways for WCPOS - [Payment Gateways](/payment/gateways.md): Payment gateways for WCPOS - [Email Invoice Gateway](/payment/gateways/email-invoice.md): Send payment invoices to customers via email in WCPOS - [PayPal Reader (Zettle) Gateway](/payment/gateways/paypal-reader.md): Accept in-person card payments through a PayPal Reader (Zettle) card terminal in WCPOS - [Square Terminal Gateway](/payment/gateways/square-terminal.md): Collect in-person payments on Square Terminal devices in WCPOS - [Stripe Terminal Gateway](/payment/gateways/stripe-terminal.md): Accept payments using Stripe Terminal hardware readers in WCPOS - [SumUp Terminal Gateway](/payment/gateways/sumup-terminal.md): Process payments through SumUp card readers in WCPOS - [Vipps MobilePay Gateway](/payment/gateways/vipps-mobilepay.md): Accept phone-based payments via QR code or push notification in WCPOS - [Web Checkout Gateway](/payment/gateways/web-checkout.md): Complete payments via the web store checkout in WCPOS ## pos Overview of the WCPOS point of sale screen layout — header, product panel, cart, navigation drawer, and which screens are Free vs Pro. - [POS Screen Overview](/pos.md): Overview of the WCPOS point of sale screen layout — header, product panel, cart, navigation drawer, and which screens are Free vs Pro. ### cart Manage the shopping cart in WCPOS including line items, quantities, discounts, fees, and customer selection. - [Cart Panel](/pos/cart.md): Manage the shopping cart in WCPOS including line items, quantities, discounts, fees, and customer selection. - [Cart Discounts](/pos/cart/discounts.md): Apply discounts at the WCPOS register — quick percentage discounts, line-item price changes, and order-level discount fees. - [Cart Line Items](/pos/cart/line-items.md): Edit cart line items in WCPOS including quantities, prices, discounts, and product details with inline editing. - [Open Orders](/pos/cart/open-orders.md): Work with multiple orders simultaneously in WCPOS including parking orders, switching between transactions, and recovering from interruptions. - [Order Actions](/pos/cart/order-actions.md): Access order management features in WCPOS including order notes, meta data, fees, shipping, and discounts. ### checkout Complete sales in WCPOS checkout including payment methods, payment processing, and order completion. - [Checkout](/pos/checkout.md): Complete sales in WCPOS checkout including payment methods, payment processing, and order completion. ### product-panel Browse, search, and add products to cart in the WCPOS product panel. Includes grid/list views and category filtering. - [Product Panel](/pos/product-panel.md): Browse, search, and add products to cart in the WCPOS product panel. Includes grid/list views and category filtering. - [Barcode Scanning](/pos/product-panel/barcode-scanning.md): Set up barcode scanning in WCPOS using USB scanners, camera scanning, or custom barcode fields. - [Meta Data Keys](/pos/product-panel/meta-data-keys.md): Copy custom product meta data onto cart and order line items in WCPOS using the Meta Data Keys setting. - [Search & Filtering](/pos/product-panel/search-filtering.md): Search and filter products in WCPOS by name, SKU, category, tags, and other attributes. - [Variable Products](/pos/product-panel/variations.md): Work with WooCommerce variable products in WCPOS including quick selection, inline expansion, and barcode scanning for variations. ### reconciliation Quick end-of-day close for WCPOS cashiers — count the drawer, run the report, compare cash and card, and sign off. - [End-of-Day Reconciliation](/pos/reconciliation.md): Quick end-of-day close for WCPOS cashiers — count the drawer, run the report, compare cash and card, and sign off. ### refunds Quick guide to issuing a refund during a sale in WCPOS — start the refund, choose where the money goes, and confirm. - [Refunds at the Till](/pos/refunds.md): Quick guide to issuing a refund during a sale in WCPOS — start the refund, choose where the money goes, and confirm. ## products Manage WooCommerce products in WCPOS, including inventory updates, price changes, and stock management. - [Products Management](/products.md): Manage WooCommerce products in WCPOS, including inventory updates, price changes, and stock management. ### pos-only-products Control product visibility between your online store and POS, including POS-only and online-only products. - [POS Only Products](/products/pos-only-products.md): Control product visibility between your online store and POS, including POS-only and online-only products. ### sync How WCPOS downloads and synchronises products from WooCommerce, including incremental sync and local storage. - [Product Synchronisation](/products/sync.md): How WCPOS downloads and synchronises products from WooCommerce, including incremental sync and local storage. ## receipts Customise WCPOS receipts using the template gallery, logicless HTML templates, and thermal printer XML templates. - [Receipts](/receipts.md): Customise WCPOS receipts using the template gallery, logicless HTML templates, and thermal printer XML templates. ### at-checkout Print and email receipts in WCPOS, including printer setup and receipt customisation options. - [Receipts](/receipts/at-checkout.md): Print and email receipts in WCPOS, including printer setup and receipt customisation options. ### cloud-printing Print WCPOS receipts to printers that aren't attached to the till — Star Online, Star CloudPRNT, Epson Server Direct Print, and PrintNode. - [Cloud Printing](/receipts/cloud-printing.md): Print WCPOS receipts to printers that aren't attached to the till — Star Online, Star CloudPRNT, Epson Server Direct Print, and PrintNode. ### customise The easiest way to change how your WCPOS receipt looks — pick a different template, ask AI to tweak it, or edit it by hand. - [Customise Your Receipt](/receipts/customise.md): The easiest way to change how your WCPOS receipt looks — pick a different template, ask AI to tweak it, or edit it by hand. ### html-templates Create and customise logicless HTML receipt templates using Mustache-style placeholders. - [HTML Templates](/receipts/html-templates.md): Create and customise logicless HTML receipt templates using Mustache-style placeholders. ### receipt-data Complete reference for the canonical data contract available in WCPOS receipt templates. - [Receipt Data Reference](/receipts/receipt-data.md): Complete reference for the canonical data contract available in WCPOS receipt templates. ### thermal-templates Create XML-based receipt templates for ESC/POS thermal printers with Epson and Star support. - [Thermal Printer Templates](/receipts/thermal-templates.md): Create XML-based receipt templates for ESC/POS thermal printers with Epson and Star support. ## reference ### architecture Technical architecture of WCPOS explaining how the POS client communicates with the WooCommerce REST API. - [Architecture](/reference/architecture.md): Technical architecture of WCPOS explaining how the POS client communicates with the WooCommerce REST API. ### fiscal-compliance Where WCPOS stands on fiscal certification (France NF525, Spain VERIFACTU, Norway, Chile) and EU OSS, and the available workarounds. - [Fiscal Compliance & Certification](/reference/fiscal-compliance.md): Where WCPOS stands on fiscal certification (France NF525, Spain VERIFACTU, Norway, Chile) and EU OSS, and the available workarounds. ### gateway-template Create a custom POS-only payment gateway for WCPOS - [Gateway Template](/reference/gateway-template.md): Create a custom POS-only payment gateway for WCPOS ### pos-discounts Developer reference for how WCPOS stores POS line-item price overrides, how they interact with WooCommerce coupons, and the available filters. - [POS Discount Technical Reference](/reference/pos-discounts.md): Developer reference for how WCPOS stores POS line-item price overrides, how they interact with WooCommerce coupons, and the available filters. ### role-endpoint-access Developer reference for which WCPOS REST endpoints are accessible to each default role (administrator, shop_manager, cashier), plus token-expiry behaviour and diagnostic tips. - [Role Endpoint Access](/reference/role-endpoint-access.md): Developer reference for which WCPOS REST endpoints are accessible to each default role (administrator, shop_manager, cashier), plus token-expiry behaviour and diagnostic tips. ### wc-rest-api The WooCommerce REST API is like a set of standardised “channels” that allows store owners to connect their WooCommerce store to other applications and services. - [Understanding the WooCommerce REST API](/reference/wc-rest-api.md): The WooCommerce REST API is like a set of standardised “channels” that allows store owners to connect their WooCommerce store to other applications and services. ## reports View sales reports and analytics in WCPOS, including daily summaries, payment breakdowns, and cashier reports. - [Reports](/reports.md): View sales reports and analytics in WCPOS, including daily summaries, payment breakdowns, and cashier reports. ### reconciliation Cashier-facing end-of-day procedure in WCPOS — count the drawer, run the report, reconcile cash and card, handle variances, and sign off. - [End-of-Day Reconciliation](/reports/reconciliation.md): Cashier-facing end-of-day procedure in WCPOS — count the drawer, run the report, reconcile cash and card, handle variances, and sign off. ## settings Overview of WCPOS settings, including WordPress admin settings, store settings, and application preferences. - [Settings Overview](/settings.md): Overview of WCPOS settings, including WordPress admin settings, store settings, and application preferences. ### store Configure WCPOS store settings including general options, tax, barcode scanning, theme, and keyboard shortcuts. - [Store Settings](/settings/store.md): Configure WCPOS store settings including general options, tax, barcode scanning, theme, and keyboard shortcuts. - [Barcode Settings](/settings/store/barcode.md): Configure barcode scanning settings in WCPOS including scan delay, search actions, and camera scanning options. - [General Settings](/settings/store/general.md): Configure WCPOS store settings including currency display, number formatting, and default order status. - [Keyboard Shortcuts](/settings/store/hotkeys.md): Configure keyboard shortcuts in WCPOS for faster checkout and navigation using customisable hotkeys. - [Tax Settings](/settings/store/tax.md): Configure tax calculation and display settings in WCPOS including tax-inclusive pricing and itemised tax display. - [Theme Settings](/settings/store/theme.md): Customise WCPOS appearance with light, dark, and system themes plus accent colour options. ### wp-admin Configure WCPOS backend settings in WordPress admin including general options, checkout, and user access permissions. - [Settings in the WordPress Admin](/settings/wp-admin.md): Configure WCPOS backend settings in WordPress admin including general options, checkout, and user access permissions. - [Accessing the POS](/settings/wp-admin/access.md): Configure user roles and capabilities for WCPOS access including Administrator, Shop Manager, and Cashier permissions. - [Checkout Settings](/settings/wp-admin/checkout.md): Configure WCPOS checkout settings in WordPress admin including payment gateways and order processing. - [Customer Tax IDs](/settings/wp-admin/customer-tax-ids.md): How WCPOS stores customer tax IDs, detects which plugin's field to write to, and copies tax IDs onto orders at checkout. - [Email Notifications](/settings/wp-admin/email-notifications.md): Control which WooCommerce email notifications fire for POS orders — per-email admin, customer, and cashier toggles in WCPOS settings. - [General Settings](/settings/wp-admin/general.md): Configure WCPOS general settings in WordPress admin including POS-only products, decimal quantities, and barcode fields. - [Sessions](/settings/wp-admin/sessions.md): View active POS login sessions per user and device, and remotely sign devices out of WCPOS. - [Store Tax IDs](/settings/wp-admin/store-tax-ids.md): Configure the business tax identifiers WCPOS prints on POS receipts and invoices, including VAT, ABN, GSTIN, EIN, and company-registry numbers. ## stores Set up and manage multiple store locations in WCPOS, including per-store pricing, ATUM inventory integration, tax rates, and reports. - [Multi-Store](/stores.md): Set up and manage multiple store locations in WCPOS, including per-store pricing, ATUM inventory integration, tax rates, and reports. ### setup Step-by-step guide to creating and configuring a store location in WCPOS Pro — store details, authorized users, tax, pricing, and login behavior. - [Setting Up Stores](/stores/setup.md): Step-by-step guide to creating and configuring a store location in WCPOS Pro — store details, authorized users, tax, pricing, and login behavior. ## support Get help with WCPOS through Discord, email support, or browse troubleshooting guides and FAQs. - [Support](/support.md): Get help with WCPOS through Discord, email support, or browse troubleshooting guides and FAQs. ### logs Access and understand WCPOS logs for troubleshooting, including application logs, server-side logs, audit trails, and error messages. - [Logs](/support/logs.md): Access and understand WCPOS logs for troubleshooting, including application logs, server-side logs, audit trails, and error messages. ### notifications Understand the in-app notification bell in WCPOS — where announcements, plugin updates, and licence alerts appear. - [Notifications](/support/notifications.md): Understand the in-app notification bell in WCPOS — where announcements, plugin updates, and licence alerts appear. ### performance Optimise WCPOS performance including server configuration, checkout speed, and WooCommerce HPOS migration. - [Performance](/support/performance.md): Optimise WCPOS performance including server configuration, checkout speed, and WooCommerce HPOS migration. - [Checkout Performance](/support/performance/checkout.md): Troubleshoot slow checkout times in WCPOS by analysing execution times and identifying bottlenecks. - [Server Performance](/support/performance/server.md): Optimise WordPress server performance for WCPOS including HPOS, caching, database optimisation, and hosting recommendations. ### translations How WCPOS is translated — AI-generated from tuned rules and improved by the community. Suggest fixes for the apps and plugin in the wcpos/translations repo, and for these docs in the wcpos/docs repo. - [Contributing Translations](/support/translations.md): How WCPOS is translated — AI-generated from tuned rules and improved by the community. Suggest fixes for the apps and plugin in the wcpos/translations repo, and for these docs in the wcpos/docs repo. ### troubleshooting - [Clear All Local Data](/support/troubleshooting/clear-local-data.md): How to clear the local WCPOS database and trigger a fresh sync from your WooCommerce store. - [Troubleshooting "There has been a critical error on this website."](/support/troubleshooting/critical-error.md): Fix the WordPress critical error in WCPOS by checking WooCommerce fatal error logs and identifying the cause. - [Plugin Conflicts](/support/troubleshooting/plugin-conflicts.md): Identify and resolve WordPress plugin conflicts affecting WCPOS using systematic troubleshooting methods. - [Troubleshooting "Cannot read properties of undefined (reading 'data')" Error](/support/troubleshooting/response-error.md): Fix the "Cannot read properties of undefined" error in WCPOS caused by empty server responses or plugin conflicts. ## Optional - [WCPOS Website](https://wcpos.com): Product website and downloads - [GitHub](https://github.com/wcpos): Source code and issue tracker - [Discord](https://wcpos.com/discord): Community support chat - [WordPress.org plugin](https://wordpress.org/plugins/woocommerce-pos/): Free version on the WordPress plugin directory - [WCPOS Pro](https://wcpos.com/pro): Pro features and licensing --- # Full Documentation Content [WooCommerce REST APIThe WooCommerce REST API is like a set of standardised “channels” that allows store owners to connect their WooCommerce store to other applications and services.](/reference/wc-rest-api.md) [ArchitectureTechnical architecture of WCPOS explaining how the POS client communicates with the WooCommerce REST API.](/reference/architecture.md) [Role Endpoint AccessDeveloper reference for which WCPOS REST endpoints are accessible to each default role (administrator, shop\_manager, cashier), plus token-expiry behaviour and diagnostic tips.](/reference/role-endpoint-access.md) [Fiscal ComplianceWhere WCPOS stands on fiscal certification (France NF525, Spain VERIFACTU, Norway, Chile) and EU OSS, and the available workarounds.](/reference/fiscal-compliance.md) [POS DiscountsDeveloper reference for how WCPOS stores POS line-item price overrides, how they interact with WooCommerce coupons, and the available filters.](/reference/pos-discounts.md) [Gateway TemplateCreate a custom POS-only payment gateway for WCPOS](/reference/gateway-template.md) --- [Products2 items](/products/.md) [Orders1 item](/orders/.md) [CustomersManage WooCommerce customers in WCPOS, including customer lookup, editing details, and viewing order history.](/customers/.md) [Stores1 item](/stores/.md) [Reports1 item](/reports/.md) --- [Clear Local DataHow to clear the local WCPOS database and trigger a fresh sync from your WooCommerce store.](/support/troubleshooting/clear-local-data.md) [Critical ErrorFix the WordPress critical error in WCPOS by checking WooCommerce fatal error logs and identifying the cause.](/support/troubleshooting/critical-error.md) [Response ErrorFix the "Cannot read properties of undefined" error in WCPOS caused by empty server responses or plugin conflicts.](/support/troubleshooting/response-error.md) [Plugin ConflictsIdentify and resolve WordPress plugin conflicts affecting WCPOS using systematic troubleshooting methods.](/support/troubleshooting/plugin-conflicts.md) --- # Coupons Pro Feature The Coupons screen and the ability to apply coupons at the register require [WCPOS Pro](/getting-started/pro-license.md). Free users see a blurred preview of the Coupons screen but cannot view coupon details or apply codes in the cart. The Coupons screen lets you browse and look up your WooCommerce coupons from inside the POS, and the **Add Coupon** button in the cart applies them to the current order. Coupons themselves are still created and managed in WooCommerce — the POS syncs them down and validates them locally for instant feedback at the till. ## Interface Overview[​](#interface-overview "Direct link to Interface Overview") ### Header Actions[​](#header-actions "Direct link to Header Actions") At the top of the screen: * **Search bar** — Find a coupon by code * **Display settings** () — Configure visible columns ### Coupons Table[​](#coupons-table "Direct link to Coupons Table") The main area displays your synced coupons with: * **Code** — The coupon code customers enter * **Description** — Internal description (also used as the receipt label when set) * **Discount Type** — Percentage, fixed cart, or fixed product * **Amount** — The discount value * **Used / Limit** — Times used and overall usage limit * **Expires** — Expiry date, or blank if none * **Actions** — Three-dot menu ### Footer[​](#footer "Direct link to Footer") * Coupon count with sync button (). **Long press** for Clear and Refresh options. ## Coupon Types[​](#coupon-types "Direct link to Coupon Types") WCPOS supports the three standard WooCommerce coupon types: | Type | What it does | Example | | -------------------------- | --------------------------------------------------------- | --------------------- | | **Percentage discount** | Reduces the cart subtotal by a percentage | `10%` off the order | | **Fixed cart discount** | Reduces the cart total by a fixed amount | `$5` off the order | | **Fixed product discount** | Reduces matching product lines by a fixed per-unit amount | `$2` off each T-shirt | All three types respect the same validation rules (expiry, usage limits, product/category restrictions, etc.). ## Creating Coupons[​](#creating-coupons "Direct link to Creating Coupons") Coupons are created in WooCommerce, not in the POS. Go to **WP Admin → Marketing → Coupons → Add coupon**: 1. **Coupon code** — what cashiers type at the register. Codes are case-insensitive. 2. **Description** — internal note. WCPOS uses this as the discount label on receipts when set, so prefer a customer-friendly phrase like "Manager Discount 10%" over an internal code. 3. **Discount type** — percentage, fixed cart, or fixed product. 4. **Coupon amount** — the value of the discount. 5. **Expiry date** — optional. After this date the coupon will be rejected. ### Usage restriction[​](#usage-restriction "Direct link to Usage restriction") | Restriction | What it does | Example | | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | **Minimum / maximum spend** | Coupon only applies above/below a subtotal threshold | Valid only on orders over `$50` | | **Individual use only** | Prevents this coupon from being combined with any other coupon | "VIP20" can't be stacked with "SALE10" | | **Exclude sale items** | Skips items already on sale (and any line where a cashier has lowered the price at the till — see [POS price overrides](/pos/cart/discounts.md#how-pos-price-changes-interact-with-coupons)) | Clearance items don't get the extra discount | | **Products / Exclude products** | Restrict the coupon to (or away from) specific products | Only applies to "Espresso Beans" | | **Product categories / Exclude categories** | Restrict by category. Misc/custom products created at the POS respect categories assigned through the POS as well | Only applies to the "Drinks" category | | **Allowed emails** | Limit the coupon to specific customer email addresses (supports `*` wildcards) | `*@yourcompany.com` for staff only | ### Usage limits[​](#usage-limits "Direct link to Usage limits") | Limit | What it does | | -------------------------- | -------------------------------------------------------------------------------- | | **Usage limit per coupon** | Total times this code can be used across all customers | | **Usage limit per user** | Times one customer can use it | | **Limit usage to X items** | For fixed-product coupons, cap the number of qualifying items discounted per use | []() Tips for POS use * Create a **"Manager 10%"** coupon (10% off, no minimum spend, no expiry, single-use restriction off) and give the code to managers — staff can apply it at the till for ad-hoc adjustments and you keep a tracked discount in reports. * Create a **"Loyalty $5"** coupon for repeat-customer rewards. * For one-off promotions, set a short expiry date so the code can't be reused later by mistake. * Setting **Description** to the phrase you'd like printed on receipts is the fastest way to brand your discounts. ## Applying a Coupon at the Register[​](#applying-a-coupon-at-the-register "Direct link to Applying a Coupon at the Register") Tap **Add Coupon** in the cart, then type the code or search by description. The coupon validates instantly against synced data and appears as a removable pill above the cart totals. For the full cashier workflow — search, coupon pills, stacking multiple coupons, and resolving validation errors — see **[Applying Coupons at the Till](/coupons/applying-coupons.md)**. ## How Validation Works[​](#how-validation-works "Direct link to How Validation Works") When a code is entered, the POS checks all the same rules WooCommerce would check on the server: * Coupon exists and is not expired * Usage limits aren't exceeded (overall and per-user) * Minimum/maximum spend is met * "Individual use" coupons don't conflict with already-applied coupons * Product/category restrictions match the cart contents * Email restrictions match the selected customer (or are skipped on Guest orders) * Sale items are excluded if **Exclude sale items** is enabled If any check fails, the cashier sees a specific error message (e.g., "This coupon has expired" or "Minimum spend not reached"). The same checks run again on the server when the order is submitted — the local validation is for speed, not for trust. ## Sync Behaviour[​](#sync-behaviour "Direct link to Sync Behaviour") Coupons sync from WooCommerce to the device via the standard WCPOS replication pipeline: * New coupons created in WP Admin appear in the POS on the next sync. * Updates to existing coupons (usage count, expiry changes, etc.) sync down automatically. * Coupons are stored locally in IndexedDB so they remain available offline. If you just created a coupon in WP Admin and don't see it yet, the sync may not have run. From the Coupons screen footer, tap the sync icon () to refresh — long-press for **Clear and refresh** if you need a fresh fetch. ## Connectivity[​](#connectivity "Direct link to Connectivity") * **Applying coupons** works offline because validation is client-side from synced data. * **Completing checkout** still requires a server connection — the server re-validates and is the authoritative source for the final order total. * **Creating or editing coupons** happens in WP Admin and requires a connection to your WordPress site. ## How Coupons Interact with POS Discounts[​](#how-coupons-interact-with-pos-discounts "Direct link to How Coupons Interact with POS Discounts") When a cashier lowers a line price at the till and a coupon is then applied, the coupon calculates against the **lowered price**, not the original. POS-lowered lines are treated as "on sale" — coupons with **Exclude sale items** enabled will skip them. See [Discounts](/pos/cart/discounts.md#how-pos-price-changes-interact-with-coupons) for more. ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [DiscountsQuick discounts, line-item price changes, and order-level fees](/pos/cart/discounts.md) [ReportsSee coupon usage in your daily reports](/reports/.md) [POS Discount ReferenceDeveloper reference for how POS discounts interact with coupons](/reference/pos-discounts.md) --- # Applying Coupons at the Till Pro Feature Applying coupons at the register requires [WCPOS Pro](/getting-started/pro-license.md). Free users can see the [Coupons](/coupons/.md) screen as a blurred preview but the **Add Coupon** action is disabled in the cart. This page covers the at-counter workflow — finding a coupon, applying it, stacking multiple coupons, and dealing with errors. For coupon types, setup, and validation rules see [Coupons](/coupons/.md); for ad-hoc discounts a cashier creates on the fly see [Cart Discounts](/pos/cart/discounts.md). ## The Add Coupon flow[​](#the-add-coupon-flow "Direct link to The Add Coupon flow") Below the cart line items there's an **Add Coupon** button. Tapping it opens a small input where you can either type a code or search. 1. Tap **Add Coupon** in the cart 2. Start typing — the input doubles as a search across all synced coupons (code and description) 3. Pick the coupon from the suggestion list, or finish typing the code and press **Enter** The coupon validates instantly against your locally-synced data — there's no round-trip to the server — and the discount appears on the cart total. If you change cart contents afterwards (add an item, change a quantity, swap a customer), the discount recalculates automatically. Code vs. search Cashiers who know the code (e.g. "SUMMER10") can type it and hit Enter — fastest path. The search is for when a customer hands over a printed coupon and the staff member doesn't remember the exact code, or when looking up a loyalty discount by customer name. ## Coupon pills in the cart[​](#coupon-pills-in-the-cart "Direct link to Coupon pills in the cart") Each applied coupon appears as a small **pill** in the cart, sitting just above the totals. The pill shows the coupon's description (or code, if no description is set) and the amount it discounted. Tap the **×** on a pill to remove that coupon — the cart total recalculates immediately. Pills stack vertically when more than one coupon is applied. The order shown is the order they were added — and that order matters for [sequential discounts](#sequential-discounts). Receipt labels The pill text is also what prints on the receipt. If you'd like a cleaner label than the raw coupon code (e.g. *"Loyalty Discount"* rather than *"LOYAL10"*), set the **Description** field on the coupon in `WP Admin → Marketing → Coupons`. WCPOS uses the description as the discount label whenever it's set. ## Sequential discounts[​](#sequential-discounts "Direct link to Sequential discounts") You can apply more than one coupon to an order. WooCommerce treats them **sequentially** — each coupon discounts the running subtotal left by the previous one, not the original cart total. ### Worked example[​](#worked-example "Direct link to Worked example") Cart subtotal: **$100.00** | Step | Coupon | Calculation | Running total | | ---- | ------------------------ | ----------- | ------------- | | 1 | `LOYAL10` (10% off) | $100 × 0.90 | **$90.00** | | 2 | `WELCOME5` ($5 off cart) | $90 − $5 | **$85.00** | | 3 | `EXTRA20` (20% off) | $85 × 0.80 | **$68.00** | The order they're applied in changes the final number. Two 10% coupons stack to 19% off the original (not 20%), because the second 10% applies to the already-discounted total. ### When coupons can't stack[​](#when-coupons-cant-stack "Direct link to When coupons can't stack") A coupon configured with **Individual use only** in WooCommerce blocks any other coupon from being applied alongside it. If `SUMMER25` is individual-use: * Apply `SUMMER25` first → adding any other coupon shows *"This coupon cannot be combined with other coupons."* * Apply other coupons first → adding `SUMMER25` shows the same message. Remove the conflicting coupon to apply the other. ### Fixed-product coupons[​](#fixed-product-coupons "Direct link to Fixed-product coupons") A **fixed product discount** coupon (e.g. *$2 off each T-shirt*) only discounts the line items it matches — it doesn't reduce the running subtotal for other coupons. Stacking it with a percentage cart coupon is safe and predictable. ## Removing a coupon[​](#removing-a-coupon "Direct link to Removing a coupon") * Tap the **×** on the coupon pill to remove that single coupon. * Clearing the cart (**More** menu → *Clear cart*) removes all applied coupons. * Removing a line item that was the *only* qualifying item for a product-restricted coupon will auto-remove the coupon and show a brief toast — "Coupon removed: no qualifying items". ## Validation errors and how to resolve them[​](#validation-errors-and-how-to-resolve-them "Direct link to Validation errors and how to resolve them") The POS runs the same validation rules as WooCommerce — see [How Validation Works](/coupons/.md#how-validation-works) for the full list. When a coupon is rejected, the cashier sees a specific message: | Message | What it means | What to do | | ----------------------------------------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | *"Coupon does not exist"* | The code wasn't found in synced data. | Check spelling. If the coupon was just created in WP Admin, run a sync from the [Coupons](/coupons/.md) screen (long-press the sync icon for **Clear and refresh**). | | *"This coupon has expired"* | Today's date is past the coupon's expiry. | Extend the expiry in WP Admin, or use a different code. | | *"Usage limit reached"* | The coupon's overall usage limit is exhausted. | Raise the limit in WP Admin, or use a different code. | | *"Customer has already used this coupon"* | The selected customer is over the per-user limit. | Switch customers, or raise the per-user limit. | | *"Minimum spend not reached"* | The cart subtotal is below the coupon's minimum. | Add more items or use a different code. | | *"Maximum spend exceeded"* | The cart subtotal is above the coupon's maximum. | Split into separate orders or use a different code. | | *"This coupon cannot be combined with other coupons"* | Either the new coupon or an already-applied one is set to **Individual use only**. | Remove the conflicting coupon, then apply the desired one. | | *"Coupon not valid for items in cart"* | None of the cart items match the coupon's product/category restrictions. | Add a qualifying item, or pick a different coupon. | | *"Coupon not valid for this customer"* | The selected customer's email doesn't match the coupon's **Allowed emails** rule. | Switch to a customer whose email matches, or remove the email restriction. | If a coupon validates locally but the order is rejected at checkout, the server re-ran validation against fresher data — usually the usage limit was hit in another sale during the same shift. Re-apply or pick another. ## Common workflows[​](#common-workflows "Direct link to Common workflows") Manager discount — ad-hoc 10% with a tracked code Create a coupon in `WP Admin → Marketing → Coupons` called something like `MGR10`: * **Discount type:** Percentage discount * **Coupon amount:** 10 * **Usage limit per coupon:** *(blank — unlimited)* * **Individual use only:** off (so it can stack with loyalty / promo codes) * **Description:** *"Manager Discount"* (this is what prints on the receipt) Share the code with managers only. The coupon shows up in WooCommerce reports as a tracked discount, unlike a [POS price override](/pos/cart/discounts.md) which now just lowers the line price. Loyalty reward — repeat-customer $5 off Create `LOYAL5`: * **Discount type:** Fixed cart discount * **Coupon amount:** 5 * **Minimum spend:** 25 *(or whatever your threshold is)* * **Usage limit per user:** 1 *(if the reward is one-time)* * **Description:** *"Loyalty Reward"* At the till, search "loyalty" to find it without having to remember the code. Single-use promo — flyer or print campaign Create one coupon per campaign with **Usage limit per coupon: 1** if it's a single-redemption flyer, or a higher number for a multi-use promo. Set a tight **Expiry date** so the code can't be reused later by mistake. For multi-use promos where each customer should only redeem once, set both **Usage limit per coupon** *and* **Usage limit per user: 1**. Stacking a manager discount on top of a coupon code the customer brought Apply the customer's code first, then the manager code. WooCommerce treats them sequentially — the manager discount calculates against the already-discounted total, which is usually what customers expect. If the customer's coupon is **Individual use only**, the manager code will be rejected. Either remove the customer's coupon first (and re-apply later if needed) or update the customer's coupon in WP Admin to allow stacking. A customer wants to return part of an order and re-ring it with a different coupon Refund the original order first (see [Refunds](/orders/refunds.md)), then start a fresh sale with the new coupon. Coupons are tied to the order at the time of sale — you can't retroactively swap a coupon on a completed order from the POS. The refund returns the usage count to the coupon so it can be applied again on the new order. ## Interaction with POS price changes[​](#interaction-with-pos-price-changes "Direct link to Interaction with POS price changes") If a cashier lowered a line price at the till (a [POS price override](/pos/cart/discounts.md)) and then applies a coupon, the coupon calculates against the **lowered price**, not the original. POS-lowered lines are treated as "on sale", so any coupon with **Exclude sale items** enabled will skip them. This is intentional — it prevents customers being double-discounted by stacking a cashier discount and a coupon against the original price. See [How POS Price Changes Interact with Coupons](/pos/cart/discounts.md#how-pos-price-changes-interact-with-coupons) for the full mechanics. ## Offline behaviour[​](#offline-behaviour "Direct link to Offline behaviour") * **Applying coupons works offline** — validation runs against locally-synced coupon data. * **Completing the sale still needs a connection** when the order is submitted (the server re-validates and writes the usage count). * **A coupon you just created in WP Admin** won't apply at the till until the next sync. From the [Coupons](/coupons/.md) screen footer, tap the sync icon () — long-press for **Clear and refresh** if you need a fresh fetch. --- # Customers Pro Feature The Customers screen requires [WCPOS Pro](/getting-started/pro-license.md). Free users can select existing customers for orders but cannot view the full customer list or edit customer details. The Customers screen provides comprehensive customer management directly within the POS. View, edit, and create customers without switching to the WooCommerce admin. ## Interface Overview[​](#interface-overview "Direct link to Interface Overview") ### Header Actions[​](#header-actions "Direct link to Header Actions") At the top of the screen: * **Search bar** - Find customers by name, email, etc. * **Add Customer** () - Create a new customer * **Display settings** () - Configure visible columns ### Customer Table[​](#customer-table "Direct link to Customer Table") The main area displays customers with: * **Avatar** - Customer profile picture (or placeholder) * **First Name** - Customer's first name * **Last Name** - Customer's last name (sortable) * **Email** - Contact email address * **Billing Address** - Full billing address * **Date Created** - When the customer was added * **Actions** - Three-dot menu ### Footer[​](#footer "Direct link to Footer") * Customer count with sync button (). **Long press** for Clear and Refresh option ## Key Features[​](#key-features "Direct link to Key Features") ### Customer Search[​](#customer-search "Direct link to Customer Search") Find customers quickly by: * First or last name * Email address * Address information ### Add New Customer[​](#add-new-customer "Direct link to Add New Customer") Create customers directly from the POS: 1. Click the icon in the header 2. Fill in customer details 3. Save the new customer The customer is created in WooCommerce and immediately available for orders. ### Edit Customer[​](#edit-customer "Direct link to Edit Customer") Update customer information: 1. Click the three-dot menu on a customer 2. Select **Edit** 3. Modify details (name, email, addresses) 4. Save changes Changes sync to WooCommerce automatically. ## Display Settings[​](#display-settings "Direct link to Display Settings") Click the sliders icon () to customise visible columns. ![Customers Settings](/img/customers-page-settings.png) Customers Display Settings ### Available Columns[​](#available-columns "Direct link to Available Columns") | Column | Description | | -------------------- | -------------------------------------- | | **Image** | Customer avatar | | **ID** | WooCommerce customer ID | | **First Name** | Customer first name | | **Last Name** | Customer last name | | **Email** | Email address | | **Role** | User role (Customer, Subscriber, etc.) | | **Username** | WordPress username | | **Billing Address** | Billing information | | **Shipping Address** | Shipping information | | **Date Created** | When customer was added | | **Date Modified** | Last update | | **Actions** | Edit, Sync, Delete | ## Customer Actions[​](#customer-actions "Direct link to Customer Actions") Click the three-dot menu (⋮) for options: * **Edit** - Modify customer details * **Sync** - Refresh customer from server * **Delete** - Remove from local database note Deleting a customer from the POS only removes them locally. The customer remains in WooCommerce and will reappear on the next sync. ## Default Customer (Guest)[​](#default-customer-guest "Direct link to Default Customer (Guest)") When no customer is selected, orders are placed as **Guest** orders. Guest orders: * Have no customer name, email, or address attached * Cannot be looked up by customer in order history * Are still visible in the Orders screen and WooCommerce admin To avoid Guest orders, select a customer from the Cart Panel before checkout. If your business requires a customer on every order, consider training cashiers to always assign one — there is no built-in setting to enforce this. ## Using Customers in Orders[​](#using-customers-in-orders "Direct link to Using Customers in Orders") To assign a customer to an order: 1. In the [Cart Panel](/pos/cart/.md), click the customer badge 2. Search for the customer by name, email, or phone number 3. Select the customer 4. The customer is now associated with the order Customer information (billing/shipping addresses) is automatically used for the order. ## Synchronization[​](#synchronization "Direct link to Synchronization") Customer data syncs between the POS and WooCommerce: * **Real-time updates** - Changes sync across all devices * **WooCommerce integration** - Customers are stored in WooCommerce * **Offline capability** - View customers even when offline ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [Cart PanelSelecting customers for orders](/pos/cart/.md) [OrdersView customer order history](/orders/.md) --- # Error Codes When WCPOS encounters an issue, it displays an error code that helps identify the problem. Each error code follows the format `[DOMAIN][CATEGORY][SPECIFIC_CODE]` to help you quickly understand the type and nature of the error. ## Error Code Format[​](#error-code-format "Direct link to Error Code Format") | Component | Description | Example | | ----------------- | --------------------- | ------------------------- | | **Domain** | The system area | `API`, `DB`, `PY`, `SY` | | **Category** | The error category | `01`, `02`, `03`, etc. | | **Specific Code** | The unique identifier | `001`, `002`, `003`, etc. | **Example:** `API04001` = API (domain) + 04 (response errors) + 001 (invalid response format) *** ## Error Domains[​](#error-domains "Direct link to Error Domains") ### [API Errors](/error-codes/api.md)[​](#api-errors "Direct link to api-errors") API errors occur when communicating with your WooCommerce server. | Category | Code Range | Description | | ---------------- | ---------- | -------------------------------------------- | | Connection | API01xxx | Network and connectivity issues | | Authentication | API02xxx | Login, tokens, and permission issues | | Request | API03xxx | Problems with outgoing requests | | Response | API04xxx | Problems with server responses | | Plugin/WordPress | API05xxx | Issues with WordPress or WooCommerce plugins | | Configuration | API06xxx | Setup and configuration problems | ### [Database Errors](/error-codes/db.md)[​](#database-errors "Direct link to database-errors") Database errors occur when storing or retrieving data locally. | Category | Code Range | Description | | ---------- | ---------- | ------------------------------------------ | | Connection | DB01xxx | Database connection and transaction issues | | Data | DB02xxx | Record and constraint issues | | Query | DB03xxx | Query syntax and data type issues | ### [Payment Errors](/error-codes/py.md)[​](#payment-errors "Direct link to payment-errors") Payment errors occur during checkout and payment processing. | Category | Code Range | Description | | -------- | ---------- | ------------------------------------ | | Card | PY01xxx | Issues with the payment card | | Gateway | PY02xxx | Payment gateway communication issues | ### [System Errors](/error-codes/sy.md)[​](#system-errors "Direct link to system-errors") System errors are related to device resources and system configuration. | Category | Code Range | Description | | -------- | ---------- | -------------------------------------- | | Resource | SY01xxx | Memory, disk, and permission issues | | Service | SY02xxx | Configuration and service availability | *** ## Quick Reference[​](#quick-reference "Direct link to Quick Reference") Looking for a specific error code? Use the sidebar to navigate to the domain, or search for the code directly. | Domain | Total Codes | Common Issues | | -------------------------- | ----------- | --------------------------------------------------- | | [API](/error-codes/api.md) | 39 codes | Server communication, authentication, plugin issues | | [DB](/error-codes/db.md) | 9 codes | Local data storage and retrieval | | [PY](/error-codes/py.md) | 6 codes | Payment processing | | [SY](/error-codes/sy.md) | 5 codes | Device resources and configuration | *** ## Need More Help?[​](#need-more-help "Direct link to Need More Help?") If you're still experiencing issues after following the troubleshooting steps: 1. Check the [Troubleshooting](/support/troubleshooting/response-error.md) section for more detailed guides 2. Join our [Discord community](https://wcpos.com/discord) for support 3. Report issues on [GitHub](https://github.com/wcpos) --- # API Errors API errors occur when communicating with your WooCommerce server. These errors are prefixed with `API` and are organized into the following categories: ## Categories[​](#categories "Direct link to Categories") | Category | Code Range | Description | | ------------------------------------------- | ---------- | -------------------------------------------- | | [Connection](#connection-errors) | API01xxx | Network and connectivity issues | | [Authentication](#authentication-errors) | API02xxx | Login, tokens, and permission issues | | [Request](#request-errors) | API03xxx | Problems with outgoing requests | | [Response](#response-errors) | API04xxx | Problems with server responses | | [Plugin/WordPress](#pluginwordpress-errors) | API05xxx | Issues with WordPress or WooCommerce plugins | | [Configuration](#configuration-errors) | API06xxx | Setup and configuration problems | *** ## Connection Errors[​](#connection-errors "Direct link to Connection Errors") Network and connectivity issues between the POS and your server. | Code | Name | Description | | ------------------------------------ | --------------------- | -------------------------------------------- | | [API01001](/error-codes/API01001.md) | Connection Timeout | The server took too long to respond | | [API01002](/error-codes/API01002.md) | Connection Refused | The server refused the connection | | [API01003](/error-codes/API01003.md) | Connection Reset | The connection was unexpectedly closed | | [API01004](/error-codes/API01004.md) | DNS Resolution Failed | Could not resolve the server address | | [API01005](/error-codes/API01005.md) | SSL Certificate Error | Problem with the site's security certificate | | [API01006](/error-codes/API01006.md) | Network Unreachable | Cannot reach the network | | [API01007](/error-codes/API01007.md) | Device Offline | Your device is not connected to the internet | | [API01008](/error-codes/API01008.md) | Website Unavailable | The website is not responding | ## Authentication Errors[​](#authentication-errors "Direct link to Authentication Errors") Issues with login, sessions, and permissions. | Code | Name | Description | | ------------------------------------ | ------------------------ | ------------------------------------------------ | | [API02001](/error-codes/API02001.md) | Invalid Credentials | Username or password is incorrect | | [API02002](/error-codes/API02002.md) | Token Expired | Your session has expired | | [API02003](/error-codes/API02003.md) | Token Invalid | The authentication token is not valid | | [API02004](/error-codes/API02004.md) | User Not Authorized | You don't have permission to perform this action | | [API02005](/error-codes/API02005.md) | Insufficient Permissions | Your user role lacks required permissions | | [API02006](/error-codes/API02006.md) | API Key Invalid | The WooCommerce API key is not valid | | [API02007](/error-codes/API02007.md) | Token Refresh Failed | Could not refresh your session | | [API02008](/error-codes/API02008.md) | Refresh Token Invalid | The refresh token is not valid | | [API02009](/error-codes/API02009.md) | Refresh Token Expired | The refresh token has expired | | [API02010](/error-codes/API02010.md) | Auth Required | Authentication is required for this action | ## Request Errors[​](#request-errors "Direct link to Request Errors") Problems with the requests sent to the server. | Code | Name | Description | | ------------------------------------ | --------------------------- | ----------------------------------------- | | [API03001](/error-codes/API03001.md) | Invalid Request Format | The request format is not correct | | [API03002](/error-codes/API03002.md) | Missing Required Parameters | Required data is missing from the request | | [API03003](/error-codes/API03003.md) | Invalid Parameter Value | A parameter has an invalid value | | [API03004](/error-codes/API03004.md) | Request Too Large | The request exceeds size limits | | [API03005](/error-codes/API03005.md) | Rate Limit Exceeded | Too many requests in a short time | | [API03006](/error-codes/API03006.md) | Unsupported Method | The HTTP method is not supported | | [API03007](/error-codes/API03007.md) | Request Queue Full | Too many pending requests | ## Response Errors[​](#response-errors "Direct link to Response Errors") Problems with the responses received from the server. | Code | Name | Description | | ------------------------------------ | ------------------------ | ------------------------------------------- | | [API04001](/error-codes/API04001.md) | Invalid Response Format | The server response format is not valid | | [API04002](/error-codes/API04002.md) | Unexpected Response Code | Received an unexpected HTTP status code | | [API04003](/error-codes/API04003.md) | Malformed JSON Response | The JSON response is corrupted or invalid | | [API04004](/error-codes/API04004.md) | Missing Response Data | Expected data is missing from the response | | [API04005](/error-codes/API04005.md) | JSON Recovery Attempted | Attempted to recover from malformed JSON | | [API04006](/error-codes/API04006.md) | Resource Not Found | The requested resource does not exist (404) | ## Plugin/WordPress Errors[​](#pluginwordpress-errors "Direct link to Plugin/WordPress Errors") Issues with WordPress, WooCommerce, or the WCPOS plugin. | Code | Name | Description | | ------------------------------------ | ------------------------ | ------------------------------------ | | [API05001](/error-codes/API05001.md) | WooCommerce API Disabled | The WooCommerce REST API is disabled | | [API05002](/error-codes/API05002.md) | WCPOS Plugin Not Found | The WCPOS plugin is not installed | | [API05003](/error-codes/API05003.md) | WCPOS Plugin Outdated | The WCPOS plugin needs updating | | [API05004](/error-codes/API05004.md) | WordPress API Disabled | The WordPress REST API is disabled | | [API05005](/error-codes/API05005.md) | Plugin Not Found | A required plugin is not installed | ## Configuration Errors[​](#configuration-errors "Direct link to Configuration Errors") Setup and configuration problems. | Code | Name | Description | | ------------------------------------ | -------------------------- | ----------------------------------- | | [API06001](/error-codes/API06001.md) | Invalid URL Format | The URL format is not valid | | [API06002](/error-codes/API06002.md) | Missing API URL | No API URL has been configured | | [API06003](/error-codes/API06003.md) | Invalid Site Configuration | The site configuration is incorrect | --- # API01001: Connection Timeout ## What This Means[​](#what-this-means "Direct link to What This Means") The POS application attempted to connect to your WooCommerce server, but the server took too long to respond. This usually indicates network latency issues or an overloaded server. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Slow internet connection** — Your network connection may be experiencing high latency * **Server overload** — Your WordPress server may be processing too many requests * **Large data requests** — Requesting too much data at once can cause timeouts * **Firewall or proxy delays** — Network security devices may be adding latency ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check Your Internet Connection[​](#1-check-your-internet-connection "Direct link to 1. Check Your Internet Connection") Test your internet speed and stability. Try loading your WooCommerce admin panel in a browser to see if it responds slowly. ### 2. Reduce Server Load[​](#2-reduce-server-load "Direct link to 2. Reduce Server Load") If your server is overloaded: * Consider upgrading your hosting plan * Disable unnecessary plugins temporarily * Check for heavy cron jobs or background processes ### 3. Optimise Server Response Time[​](#3-optimise-server-response-time "Direct link to 3. Optimise Server Response Time") Contact your hosting provider about: * Enabling PHP opcache * Increasing PHP memory limits * Using server-side caching ### 4. Increase Timeout Settings[​](#4-increase-timeout-settings "Direct link to 4. Increase Timeout Settings") If your server legitimately needs more time: * Check if your hosting provider allows increasing PHP execution time * Consider using a CDN to reduce latency ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API01002](/error-codes/API01002.md) — Connection Refused * [API01008](/error-codes/API01008.md) — Website Unavailable --- # API01002: Connection Refused ## What This Means[​](#what-this-means "Direct link to What This Means") The server actively refused the connection attempt. This is different from a timeout — the server responded, but said "no." ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Server is down** — The web server (Apache/Nginx) may not be running * **Wrong port** — Attempting to connect on the wrong port * **Firewall blocking** — A firewall is blocking the connection * **IP restrictions** — Your IP address may be blocked ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Verify the Server is Running[​](#1-verify-the-server-is-running "Direct link to 1. Verify the Server is Running") Try accessing your WordPress site directly in a browser. If it's not loading, contact your hosting provider. ### 2. Check the URL Configuration[​](#2-check-the-url-configuration "Direct link to 2. Check the URL Configuration") Ensure you're using the correct URL: * Verify `http://` vs `https://` * Check for typos in the domain name * Confirm the correct port if using a non-standard one ### 3. Check Firewall Settings[​](#3-check-firewall-settings "Direct link to 3. Check Firewall Settings") If you have access to your server: * Verify that port 80 (HTTP) or 443 (HTTPS) is open * Check if your IP is whitelisted * Review any security plugins that may block API access ### 4. Contact Your Hosting Provider[​](#4-contact-your-hosting-provider "Direct link to 4. Contact Your Hosting Provider") They can check: * Server status and logs * Firewall configurations * Whether your IP has been blocked ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API01001](/error-codes/API01001.md) — Connection Timeout * [API01006](/error-codes/API01006.md) — Network Unreachable --- # API01003: Connection Reset ## What This Means[​](#what-this-means "Direct link to What This Means") The connection to the server was established but then unexpectedly closed. This typically happens mid-communication when something interrupts the connection. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Server crash** — The server process may have crashed during the request * **Memory limits** — PHP ran out of memory and was killed * **Timeout mid-request** — The server timed out while processing * **Network instability** — Intermittent network issues * **Security software** — Aggressive security settings closing connections ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check Server Error Logs[​](#1-check-server-error-logs "Direct link to 1. Check Server Error Logs") Look in your WordPress error logs or hosting control panel for related errors around the time of the reset. ### 2. Increase PHP Memory Limit[​](#2-increase-php-memory-limit "Direct link to 2. Increase PHP Memory Limit") In your `wp-config.php`: ``` define('WP_MEMORY_LIMIT', '256M'); ``` ### 3. Check for Plugin Conflicts[​](#3-check-for-plugin-conflicts "Direct link to 3. Check for Plugin Conflicts") A plugin may be causing PHP to crash: * Temporarily disable plugins * Re-enable one by one to find the culprit ### 4. Review Server Resources[​](#4-review-server-resources "Direct link to 4. Review Server Resources") Contact your hosting provider to check: * PHP process limits * Memory usage at the time of error * Server stability logs ### 5. Test Network Stability[​](#5-test-network-stability "Direct link to 5. Test Network Stability") If on WiFi, try a wired connection. If the issue persists across different networks, it's likely server-side. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API01001](/error-codes/API01001.md) — Connection Timeout * [API01002](/error-codes/API01002.md) — Connection Refused --- # API01004: DNS Resolution Failed ## What This Means[​](#what-this-means "Direct link to What This Means") The POS could not convert your website's domain name (e.g., `yourstore.com`) into an IP address. DNS (Domain Name System) is like the internet's phone book — if it can't find the listing, it can't make the connection. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Typo in domain name** — The URL may have a spelling error * **DNS server issues** — Your DNS server is not responding * **Domain expired** — The domain registration may have lapsed * **DNS propagation** — Recent DNS changes haven't propagated yet * **Local DNS cache** — Outdated DNS information cached on your device ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Verify the Domain Name[​](#1-verify-the-domain-name "Direct link to 1. Verify the Domain Name") Double-check the URL for typos. Try accessing the site in a browser. ### 2. Check Domain Status[​](#2-check-domain-status "Direct link to 2. Check Domain Status") Use a WHOIS lookup to verify: * The domain is still registered * It hasn't expired * DNS records are configured ### 3. Clear DNS Cache[​](#3-clear-dns-cache "Direct link to 3. Clear DNS Cache") **On your device:** macOS: ``` sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder ``` Windows: ``` ipconfig /flushdns ``` ### 4. Try Alternative DNS[​](#4-try-alternative-dns "Direct link to 4. Try Alternative DNS") Switch to a public DNS server like: * Google: `8.8.8.8` and `8.8.4.4` * Cloudflare: `1.1.1.1` ### 5. Wait for DNS Propagation[​](#5-wait-for-dns-propagation "Direct link to 5. Wait for DNS Propagation") If you recently changed DNS settings, wait 24-48 hours for full propagation. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API01006](/error-codes/API01006.md) — Network Unreachable * [API06001](/error-codes/API06001.md) — Invalid URL Format --- # API01005: SSL Certificate Error ## What This Means[​](#what-this-means "Direct link to What This Means") There's a problem with your website's SSL/TLS certificate. This certificate is what makes the connection secure (HTTPS). The POS won't connect to sites with invalid certificates to protect your data. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Expired certificate** — SSL certificates need to be renewed periodically * **Self-signed certificate** — Not issued by a trusted authority * **Wrong domain** — Certificate doesn't match the domain name * **Incomplete certificate chain** — Missing intermediate certificates * **Mixed content** — Some resources loaded over HTTP instead of HTTPS ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check Certificate Status[​](#1-check-certificate-status "Direct link to 1. Check Certificate Status") Visit your site in a browser and click the padlock icon to view certificate details. Look for: * Expiration date * Issued to (should match your domain) * Issued by (should be a recognized authority) ### 2. Renew Expired Certificate[​](#2-renew-expired-certificate "Direct link to 2. Renew Expired Certificate") If expired: * Most hosting providers offer free Let's Encrypt certificates * Contact your hosting provider to renew * Check if auto-renewal is enabled ### 3. Fix Certificate Mismatch[​](#3-fix-certificate-mismatch "Direct link to 3. Fix Certificate Mismatch") Ensure the certificate covers: * Your exact domain (`yourstore.com`) * WWW variant (`www.yourstore.com`) if used * Consider a wildcard certificate (`*.yourstore.com`) ### 4. Install Missing Intermediate Certificates[​](#4-install-missing-intermediate-certificates "Direct link to 4. Install Missing Intermediate Certificates") Use an SSL checker tool (like SSL Labs) to identify missing certificates. Your hosting provider can help install them. ### 5. Force HTTPS[​](#5-force-https "Direct link to 5. Force HTTPS") In WordPress, ensure: * Site URL uses `https://` * Force SSL is enabled in WooCommerce settings ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API01002](/error-codes/API01002.md) — Connection Refused * [API06001](/error-codes/API06001.md) — Invalid URL Format --- # API01006: Network Unreachable ## What This Means[​](#what-this-means "Direct link to What This Means") The POS cannot establish a route to the server. This is a network-level issue — the data packets can't find a path to your server. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Network configuration issues** — Incorrect gateway or routing settings * **ISP problems** — Your internet service provider is having issues * **VPN interference** — A VPN may be routing traffic incorrectly * **Server network issues** — The server's network may be down ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check Your Internet Connection[​](#1-check-your-internet-connection "Direct link to 1. Check Your Internet Connection") * Try accessing other websites * Restart your router/modem * Verify you're connected to the network ### 2. Disable VPN Temporarily[​](#2-disable-vpn-temporarily "Direct link to 2. Disable VPN Temporarily") If using a VPN: * Disconnect and try again * Try a different VPN server * Check if the VPN allows access to your server's location ### 3. Check with Your ISP[​](#3-check-with-your-isp "Direct link to 3. Check with Your ISP") Contact your internet service provider if: * Other sites are also unreachable * The issue persists after restarting network equipment ### 4. Verify Server Status[​](#4-verify-server-status "Direct link to 4. Verify Server Status") * Check if your hosting provider reports any network issues * Try accessing your site from a different network (e.g., mobile data) * Use online tools to check if the site is down for everyone ### 5. Check Firewall Settings[​](#5-check-firewall-settings "Direct link to 5. Check Firewall Settings") Ensure your device's firewall isn't blocking outgoing connections to your server. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API01007](/error-codes/API01007.md) — Device Offline * [API01002](/error-codes/API01002.md) — Connection Refused --- # API01007: Device Offline ## What This Means[​](#what-this-means "Direct link to What This Means") Your device is not connected to the internet. The POS detected that there's no active network connection. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **WiFi disconnected** — Your device lost its WiFi connection * **Ethernet unplugged** — The network cable is disconnected * **Airplane mode enabled** — All wireless connections are disabled * **Network adapter disabled** — The network interface is turned off ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check WiFi Connection[​](#1-check-wifi-connection "Direct link to 1. Check WiFi Connection") * Verify WiFi is enabled on your device * Ensure you're connected to the correct network * Check the WiFi signal strength ### 2. Check Physical Connections[​](#2-check-physical-connections "Direct link to 2. Check Physical Connections") If using ethernet: * Verify the cable is securely plugged in * Try a different cable or port * Check the network switch/router lights ### 3. Disable Airplane Mode[​](#3-disable-airplane-mode "Direct link to 3. Disable Airplane Mode") Check if airplane mode is accidentally enabled and disable it. ### 4. Restart Network Adapter[​](#4-restart-network-adapter "Direct link to 4. Restart Network Adapter") **Windows:** * Open Network Connections * Right-click your adapter → Disable, then Enable **macOS:** * Turn WiFi off and on from the menu bar * Or: System Preferences → Network → Turn off/on ### 5. Restart Your Device[​](#5-restart-your-device "Direct link to 5. Restart Your Device") Sometimes a simple restart resolves network detection issues. ## Offline Mode[​](#offline-mode "Direct link to Offline Mode") While offline, WCPOS can still: * Browse and search locally cached products * Browse and search locally cached customers * Start new orders and add items to the cart * View previously synced data **Requires connectivity:** * Completing/checking out orders * Creating new customers When connectivity is restored, the POS will automatically resume normal operations. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API01006](/error-codes/API01006.md) — Network Unreachable * [API01008](/error-codes/API01008.md) — Website Unavailable --- # API01008: Website Unavailable ## What This Means[​](#what-this-means "Direct link to What This Means") The POS can reach the internet, but your specific website is not responding. The server hosting your WooCommerce store appears to be down or unreachable. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Server maintenance** — Your hosting provider may be performing updates * **Server crash** — The web server has stopped unexpectedly * **Resource limits exceeded** — Your hosting account hit its limits * **DDoS attack** — The server is overwhelmed by malicious traffic * **Domain/hosting expired** — Your hosting or domain has lapsed ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Verify the Site is Down[​](#1-verify-the-site-is-down "Direct link to 1. Verify the Site is Down") Try accessing your site directly in a browser. If it doesn't load, the issue is server-side. ### 2. Check Hosting Provider Status[​](#2-check-hosting-provider-status "Direct link to 2. Check Hosting Provider Status") * Visit your hosting provider's status page * Check for scheduled maintenance * Look for reported outages ### 3. Review Hosting Account[​](#3-review-hosting-account "Direct link to 3. Review Hosting Account") Log into your hosting control panel: * Check if your account is active * Verify you haven't exceeded resource limits * Look for any suspension notices ### 4. Contact Hosting Support[​](#4-contact-hosting-support "Direct link to 4. Contact Hosting Support") If everything looks normal on your end, contact your hosting provider. They can: * Check server status * Review server logs * Restart services if needed ### 5. Wait and Retry[​](#5-wait-and-retry "Direct link to 5. Wait and Retry") If it's a temporary outage: * Wait 15-30 minutes * The POS will automatically retry connections * Cached data remains available offline ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API01001](/error-codes/API01001.md) — Connection Timeout * [API01002](/error-codes/API01002.md) — Connection Refused --- # API02001: Invalid Credentials ## What This Means[​](#what-this-means "Direct link to What This Means") The username or password you entered is incorrect. The server rejected the login attempt because the credentials don't match any valid account. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Typo in username or password** — Check for caps lock or extra spaces * **Wrong account** — Using credentials for a different site * **Password recently changed** — The password was updated but the POS has the old one * **Account deleted** — The user account no longer exists ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | --------------------------------------- | ------------------------- | | `woocommerce_rest_authentication_error` | WooCommerce REST API | | `jwt_auth_failed` | JWT Authentication plugin | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Verify Your Credentials[​](#1-verify-your-credentials "Direct link to 1. Verify Your Credentials") * Double-check your username (usually email or WordPress username) * Verify the password is correct * Try logging into WordPress admin directly to confirm ### 2. Reset Your Password[​](#2-reset-your-password "Direct link to 2. Reset Your Password") If you've forgotten your password: 1. Go to your WordPress login page 2. Click "Lost your password?" 3. Enter your email to receive a reset link 4. Update your password 5. Log into the POS with the new password ### 3. Check the User Account[​](#3-check-the-user-account "Direct link to 3. Check the User Account") In WordPress Admin: * Go to Users → All Users * Verify the account exists * Check that it has appropriate POS access permissions ### 4. Clear Saved Credentials[​](#4-clear-saved-credentials "Direct link to 4. Clear Saved Credentials") In the POS: * Log out completely * Clear any saved/cached login information * Re-enter credentials fresh ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02004](/error-codes/API02004.md) — User Not Authorized * [API02010](/error-codes/API02010.md) — Auth Required --- # API02002: Token Expired ## What This Means[​](#what-this-means "Direct link to What This Means") Your authentication session has expired. For security reasons, login sessions don't last forever. The POS needs to refresh your authentication or you may need to log in again. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Long inactivity** — You haven't used the POS for an extended period * **Server token lifetime** — The server's token expiration is set very short * **Server time mismatch** — Server and device clocks are out of sync ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | ------------------------ | ------------------------- | | `jwt_auth_expired_token` | JWT Authentication plugin | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Log In Again[​](#1-log-in-again "Direct link to 1. Log In Again") The simplest solution is to log out and log back in: 1. Log out of the POS 2. Enter your credentials again 3. This creates a fresh session ### 2. Check Token Refresh[​](#2-check-token-refresh "Direct link to 2. Check Token Refresh") The POS should automatically refresh tokens. If it's not working: * Check your internet connection * Verify the server is accessible * See [API02007](/error-codes/API02007.md) if refresh is failing ### 3. Check Server Time[​](#3-check-server-time "Direct link to 3. Check Server Time") Token expiration depends on accurate time: * Ensure your server's clock is correct * Check that your device's time is accurate * Use automatic time sync on both ### 4. Review Token Settings[​](#4-review-token-settings "Direct link to 4. Review Token Settings") If tokens expire too quickly, you may need to adjust server settings (consult your hosting provider or WordPress administrator). ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02007](/error-codes/API02007.md) — Token Refresh Failed * [API02009](/error-codes/API02009.md) — Refresh Token Expired --- # API02003: Token Invalid ## What This Means[​](#what-this-means "Direct link to What This Means") The authentication token being used is not recognized by the server. This is different from an expired token — this token was never valid or has been revoked. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Token revoked** — An administrator revoked the session * **Token corrupted** — Data corruption during storage or transmission * **Server reset** — Server secret keys changed, invalidating all tokens * **Wrong server** — Token from a different WordPress installation ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | ------------------------ | ------------------------- | | `jwt_auth_invalid_token` | JWT Authentication plugin | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Log In Again[​](#1-log-in-again "Direct link to 1. Log In Again") Clear your session and authenticate fresh: 1. Log out completely 2. Close and reopen the POS 3. Log in with your credentials ### 2. Clear Application Data[​](#2-clear-application-data "Direct link to 2. Clear Application Data") If logging out doesn't work: * Clear the POS app cache/data * On web: Clear browser cookies and local storage for the site * On desktop: Check app settings for a "Clear Data" option ### 3. Check Server Configuration[​](#3-check-server-configuration "Direct link to 3. Check Server Configuration") If the issue affects all users: * Check if WordPress salts were changed * Verify JWT or authentication plugin settings * Review recent server changes ### 4. Verify You're on the Correct Server[​](#4-verify-youre-on-the-correct-server "Direct link to 4. Verify You're on the Correct Server") Ensure the POS is configured to connect to the right WordPress site, especially if you have multiple installations. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02002](/error-codes/API02002.md) — Token Expired * [API02008](/error-codes/API02008.md) — Refresh Token Invalid --- # API02004: User Not Authorized ## What This Means[​](#what-this-means "Direct link to What This Means") You're logged in, but your user account doesn't have permission to perform the requested action. This is an authorisation issue (what you can do) rather than an authentication issue (who you are). ## Common Causes[​](#common-causes "Direct link to Common Causes") * **User role limitations** — Your WordPress role doesn't include POS access * **POS access disabled** — Your account wasn't granted POS permissions * **Feature restrictions** — Certain features are limited to specific roles * **Store restrictions** — You may not have access to this particular store ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | ------------------------------ | -------------------- | | `rest_cannot_view` | WordPress REST API | | `woocommerce_rest_cannot_view` | WooCommerce REST API | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check User Role[​](#1-check-user-role "Direct link to 1. Check User Role") In WordPress Admin → Users: 1. Find your user account 2. Verify the role (e.g., Shop Manager, Administrator) 3. Ensure the role includes WooCommerce capabilities ### 2. Enable POS Access[​](#2-enable-pos-access "Direct link to 2. Enable POS Access") In WordPress Admin → WooCommerce → POS → Access: 1. Find the user or role 2. Enable POS access permissions 3. Save changes ### 3. Request Additional Permissions[​](#3-request-additional-permissions "Direct link to 3. Request Additional Permissions") Contact your store administrator to: * Grant your role POS access * Assign you a role with appropriate permissions * Enable specific features you need ### 4. Check Store Assignment[​](#4-check-store-assignment "Direct link to 4. Check Store Assignment") If using multiple stores: * Verify you're assigned to the correct store * Check store-specific permissions ## Required Permissions[​](#required-permissions "Direct link to Required Permissions") Different actions require different capabilities: * **View products**: Read access to products * **Create orders**: Create/edit order capabilities * **Manage customers**: Customer management capabilities * **Access reports**: View reports capabilities ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02005](/error-codes/API02005.md) — Insufficient Permissions * [API02001](/error-codes/API02001.md) — Invalid Credentials --- # API02005: Insufficient Permissions ## What This Means[​](#what-this-means "Direct link to What This Means") Your user account lacks the specific WordPress capabilities required for this action. While you have basic access, the particular operation you're attempting needs additional permissions. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Limited user role** — Your role doesn't include all needed capabilities * **Capability not assigned** — A specific capability is missing from your role * **Plugin restrictions** — A security plugin is limiting capabilities * **Custom role issues** — Custom roles may be missing capabilities ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | -------------------------------- | ------------------------------ | | `rest_forbidden` | WordPress REST API | | `rest_cannot_create` | WordPress REST API | | `rest_cannot_edit` | WordPress REST API | | `rest_cannot_delete` | WordPress REST API | | `woocommerce_rest_cannot_create` | WooCommerce REST API | | `woocommerce_rest_cannot_edit` | WooCommerce REST API | | `woocommerce_rest_cannot_delete` | WooCommerce REST API | | HTTP 403 | Any server response (fallback) | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Review Required Capabilities[​](#1-review-required-capabilities "Direct link to 1. Review Required Capabilities") Common capabilities needed for POS operations: * `manage_woocommerce` — General WooCommerce management * `edit_shop_orders` — Create and edit orders * `edit_products` — Modify product information * `edit_users` — Manage customer accounts ### 2. Upgrade User Role[​](#2-upgrade-user-role "Direct link to 2. Upgrade User Role") Ask an administrator to assign a more capable role: * **Shop Manager** — Full WooCommerce access * **Administrator** — Full site access ### 3. Add Specific Capabilities[​](#3-add-specific-capabilities "Direct link to 3. Add Specific Capabilities") If you need a custom role, add required capabilities: ``` // Example: Add POS capabilities to a custom role $role = get_role('your_custom_role'); $role->add_cap('manage_woocommerce'); $role->add_cap('edit_shop_orders'); ``` ### 4. Check Plugin Conflicts[​](#4-check-plugin-conflicts "Direct link to 4. Check Plugin Conflicts") Some security or role management plugins may restrict capabilities: * Review plugin settings * Check for capability filters * Temporarily disable to test ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02004](/error-codes/API02004.md) — User Not Authorized * [API02010](/error-codes/API02010.md) — Auth Required --- # API02006: API Key Invalid ## What This Means[​](#what-this-means "Direct link to What This Means") The WooCommerce REST API key being used is invalid. API keys are used for server-to-server authentication, and the key provided doesn't match any valid key in WooCommerce. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Key deleted** — The API key was removed from WooCommerce * **Key typo** — The key was entered incorrectly * **Wrong key pair** — Consumer key and secret don't match * **Key from different site** — Using keys generated for another installation ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Verify the API Key[​](#1-verify-the-api-key "Direct link to 1. Verify the API Key") In WordPress Admin → WooCommerce → Settings → Advanced → REST API: 1. Check if your API key exists 2. Verify it hasn't been revoked 3. Note the permissions (read/write/read-write) ### 2. Generate New API Keys[​](#2-generate-new-api-keys "Direct link to 2. Generate New API Keys") If the key is missing or invalid: 1. Go to WooCommerce → Settings → Advanced → REST API 2. Click "Add key" 3. Enter a description (e.g., "WCPOS") 4. Select the user 5. Choose "Read/Write" permissions 6. Click "Generate API key" 7. **Copy both the Consumer Key and Consumer Secret** (shown only once!) ### 3. Update POS Configuration[​](#3-update-pos-configuration "Direct link to 3. Update POS Configuration") Enter the new API keys in the POS: * Consumer Key (starts with `ck_`) * Consumer Secret (starts with `cs_`) ### 4. Check Key Permissions[​](#4-check-key-permissions "Direct link to 4. Check Key Permissions") Ensure the key has sufficient permissions: * **Read** — View data only * **Write** — Modify data only * **Read/Write** — Full access (recommended for POS) ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02001](/error-codes/API02001.md) — Invalid Credentials * [API05001](/error-codes/API05001.md) — WooCommerce API Disabled --- # API02007: Token Refresh Failed ## What This Means[​](#what-this-means "Direct link to What This Means") The POS tried to automatically renew your authentication session, but the refresh request failed. This typically means you'll need to log in again. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Refresh token expired** — The refresh token itself has expired * **Refresh token revoked** — An admin invalidated all sessions * **Server error** — The server couldn't process the refresh request * **Network issue** — Connection problem during refresh attempt ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Log In Again[​](#1-log-in-again "Direct link to 1. Log In Again") The most reliable fix: 1. Log out of the POS 2. Log back in with your credentials 3. This creates a fresh session with new tokens ### 2. Check Network Connection[​](#2-check-network-connection "Direct link to 2. Check Network Connection") If refresh is failing due to network issues: * Verify your internet connection * Try accessing your WordPress site in a browser * Wait a moment and try again ### 3. Check Server Status[​](#3-check-server-status "Direct link to 3. Check Server Status") If the server is having issues: * Verify WordPress is running properly * Check for PHP errors in your server logs * Ensure the authentication plugin is active ### 4. Clear Session Data[​](#4-clear-session-data "Direct link to 4. Clear Session Data") If issues persist: * Clear the POS app cache * Remove stored credentials * Start fresh with a new login ## Automatic Token Refresh[​](#automatic-token-refresh "Direct link to Automatic Token Refresh") WCPOS automatically refreshes tokens before they expire to maintain your session. If this process fails repeatedly, there may be a configuration issue that needs attention. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02002](/error-codes/API02002.md) — Token Expired * [API02008](/error-codes/API02008.md) — Refresh Token Invalid * [API02009](/error-codes/API02009.md) — Refresh Token Expired --- # API02008: Refresh Token Invalid ## What This Means[​](#what-this-means "Direct link to What This Means") The refresh token stored by the POS is not recognized by the server. Refresh tokens are used to obtain new access tokens without requiring you to log in again. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Token revoked** — An administrator invalidated your session * **Server secrets changed** — WordPress security keys were updated * **Data corruption** — The token was corrupted in storage * **Multiple logins** — Logging in elsewhere may have invalidated this token ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Log In Again[​](#1-log-in-again "Direct link to 1. Log In Again") Since the refresh token is invalid, you'll need to authenticate again: 1. Log out of the POS 2. Enter your username and password 3. This generates new valid tokens ### 2. Check for Revoked Sessions[​](#2-check-for-revoked-sessions "Direct link to 2. Check for Revoked Sessions") If an admin revoked sessions: * This is normal security practice * Simply log in again * Your new session will work normally ### 3. Check Server Changes[​](#3-check-server-changes "Direct link to 3. Check Server Changes") If this affects all users: * WordPress salts/keys may have changed * JWT plugin settings may have been modified * Contact your server administrator ### 4. Clear Stored Data[​](#4-clear-stored-data "Direct link to 4. Clear Stored Data") If you continue having issues: * Clear the POS application data * Remove cached credentials * Start with a clean login ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02003](/error-codes/API02003.md) — Token Invalid * [API02007](/error-codes/API02007.md) — Token Refresh Failed --- # API02009: Refresh Token Expired ## What This Means[​](#what-this-means "Direct link to What This Means") Your refresh token has exceeded its lifetime and can no longer be used to obtain new access tokens. Unlike access tokens (which expire quickly), refresh tokens typically last days or weeks but do eventually expire. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Extended inactivity** — You haven't used the POS for a long time * **Short token lifetime** — Server configured with short refresh token expiration * **Clock skew** — Device or server time is significantly off ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Log In Again[​](#1-log-in-again "Direct link to 1. Log In Again") When the refresh token expires, you must authenticate again: 1. Log out of the POS 2. Enter your credentials 3. A new refresh token will be issued ### 2. Use POS Regularly[​](#2-use-pos-regularly "Direct link to 2. Use POS Regularly") To avoid this in the future: * Use the POS regularly to keep tokens fresh * Tokens are refreshed automatically when you're active * Extended periods of inactivity will require re-login ### 3. Check Time Settings[​](#3-check-time-settings "Direct link to 3. Check Time Settings") Ensure accurate time on all systems: * Enable automatic time sync on your device * Verify server time is correct * Time differences can cause premature expiration ### 4. Adjust Token Lifetime (Advanced)[​](#4-adjust-token-lifetime-advanced "Direct link to 4. Adjust Token Lifetime (Advanced)") If tokens expire too quickly for your needs, a server administrator can adjust the refresh token lifetime in the authentication settings. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02002](/error-codes/API02002.md) — Token Expired * [API02007](/error-codes/API02007.md) — Token Refresh Failed --- # API02010: Auth Required ## What This Means[​](#what-this-means "Direct link to What This Means") The action you're trying to perform requires authentication, but you're not currently logged in. The POS needs valid credentials to access this resource. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Not logged in** — You haven't authenticated yet * **Session cleared** — Your session was cleared or expired * **Accessing protected resource** — The resource requires authentication * **App data cleared** — Stored credentials were removed ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | ------------------------- | ------------------------------ | | `rest_login_required` | WordPress REST API | | `jwt_auth_no_auth_header` | JWT Authentication plugin | | HTTP 401 | Any server response (fallback) | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Log In[​](#1-log-in "Direct link to 1. Log In") If you haven't logged in: 1. Open the POS login screen 2. Enter your WordPress credentials 3. Complete the authentication process ### 2. Check Session Status[​](#2-check-session-status "Direct link to 2. Check Session Status") If you thought you were logged in: * Your session may have expired * Look for [API02002](/error-codes/API02002.md) (Token Expired) for more details * Log in again to restore access ### 3. Verify Server Configuration[​](#3-verify-server-configuration "Direct link to 3. Verify Server Configuration") Ensure the API endpoints are properly configured: * WooCommerce REST API should be enabled * WCPOS plugin should be active * Authentication endpoints should be accessible ### 4. Check for Browser/App Issues[​](#4-check-for-browserapp-issues "Direct link to 4. Check for Browser/App Issues") If you're being logged out unexpectedly: * Clear browser cache (if using web version) * Check that cookies/local storage aren't being blocked * Verify the app has permission to store data ## What Requires Authentication?[​](#what-requires-authentication "Direct link to What Requires Authentication?") Most POS operations require authentication: * Viewing products and customers * Creating and editing orders * Processing payments * Accessing reports Only the initial login screen is accessible without authentication. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API02001](/error-codes/API02001.md) — Invalid Credentials * [API02002](/error-codes/API02002.md) — Token Expired --- # API03001: Invalid Request Format ## What This Means[​](#what-this-means "Direct link to What This Means") The request sent to the server was not in the expected format. The server couldn't understand what the POS was asking for because the request structure was incorrect. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Corrupted data** — Data was corrupted before sending * **Software bug** — An issue in the POS application * **Proxy interference** — A proxy or firewall modified the request * **Character encoding issues** — Special characters weren't encoded properly ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | ----------- | ------------------------------ | | HTTP 400 | Any server response (fallback) | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Retry the Action[​](#1-retry-the-action "Direct link to 1. Retry the Action") Sometimes this is a one-time glitch: * Wait a moment and try again * Refresh the POS and retry ### 2. Check for Special Characters[​](#2-check-for-special-characters "Direct link to 2. Check for Special Characters") If you're entering data with special characters: * Try removing emojis or unusual symbols * Use standard characters for product names, etc. ### 3. Update the POS[​](#3-update-the-pos "Direct link to 3. Update the POS") Ensure you're running the latest version: * Check for app updates * Update the WCPOS plugin on your server ### 4. Check Network Configuration[​](#4-check-network-configuration "Direct link to 4. Check Network Configuration") If you're behind a proxy: * Verify the proxy isn't modifying requests * Check firewall rules * Try accessing from a different network ### 5. Report the Issue[​](#5-report-the-issue "Direct link to 5. Report the Issue") If this happens consistently: * Note what action triggers the error * Check browser console for details (web version) * Report on [GitHub](https://github.com/wcpos) with reproduction steps ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API03002](/error-codes/API03002.md) — Missing Required Parameters * [API03003](/error-codes/API03003.md) — Invalid Parameter Value --- # API03002: Missing Required Parameters ## What This Means[​](#what-this-means "Direct link to What This Means") The request is missing data that the server needs to complete the action. Required fields were not included in the request. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Incomplete form** — Required fields weren't filled in * **Data not saved** — Form data wasn't captured properly * **Version mismatch** — Plugin expects different parameters than the POS sends * **Custom fields** — Required custom fields are missing ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Complete Required Fields[​](#1-complete-required-fields "Direct link to 1. Complete Required Fields") Check that all required information is filled in: * Customer details (if required) * Product information * Order details ### 2. Refresh and Retry[​](#2-refresh-and-retry "Direct link to 2. Refresh and Retry") The form state may be incomplete: 1. Refresh the POS 2. Re-enter the required information 3. Try the action again ### 3. Check Plugin Versions[​](#3-check-plugin-versions "Direct link to 3. Check Plugin Versions") Ensure compatibility: * Update the WCPOS plugin * Update the POS application * Both should be on compatible versions ### 4. Check Required Field Settings[​](#4-check-required-field-settings "Direct link to 4. Check Required Field Settings") In WooCommerce, some fields may be marked as required: * Review checkout field requirements * Check custom field configurations * Adjust requirements if needed ### 5. Check Custom Integrations[​](#5-check-custom-integrations "Direct link to 5. Check Custom Integrations") If using custom plugins or integrations: * They may require additional fields * Review plugin documentation * Check for conflicts ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API03001](/error-codes/API03001.md) — Invalid Request Format * [API03003](/error-codes/API03003.md) — Invalid Parameter Value --- # API03003: Invalid Parameter Value ## What This Means[​](#what-this-means "Direct link to What This Means") One of the values in your request is invalid. The data format, type, or value doesn't match what the server expects. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Wrong data type** — Text where a number is expected (or vice versa) * **Out of range** — Value exceeds allowed limits * **Invalid format** — Email, phone, or other formatted fields are incorrect * **Invalid reference** — Referencing an ID that doesn't exist ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | ----------------------------- | -------------------- | | `rest_invalid_param` | WordPress REST API | | `woocommerce_rest_invalid_id` | WooCommerce REST API | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check Input Values[​](#1-check-input-values "Direct link to 1. Check Input Values") Review the data you're submitting: * **Prices** — Should be valid numbers * **Quantities** — Should be positive integers * **Emails** — Must be valid email format * **IDs** — Must reference existing records ### 2. Look for Specific Field Errors[​](#2-look-for-specific-field-errors "Direct link to 2. Look for Specific Field Errors") The error may indicate which field is invalid: * Check the error message details * Correct the specific field * Retry the action ### 3. Verify Referenced Data Exists[​](#3-verify-referenced-data-exists "Direct link to 3. Verify Referenced Data Exists") If referencing products, customers, or other records: * Ensure the item exists in WooCommerce * Check if it was recently deleted * Sync data to refresh local records ### 4. Check Field Constraints[​](#4-check-field-constraints "Direct link to 4. Check Field Constraints") WooCommerce may have constraints: * Maximum/minimum values * Required formats * Allowed options for select fields ### 5. Clear and Re-enter[​](#5-clear-and-re-enter "Direct link to 5. Clear and Re-enter") Sometimes data gets corrupted: * Clear the problematic field * Re-enter the value from scratch * Avoid copy-pasting from other sources ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API03002](/error-codes/API03002.md) — Missing Required Parameters * [DB03002](/error-codes/DB03002.md) — Invalid Data Type --- # API03004: Request Too Large ## What This Means[​](#what-this-means "Direct link to What This Means") The request you're sending exceeds the server's size limits. This typically happens when trying to send too much data at once. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Large batch operations** — Trying to sync too many records at once * **Large images** — Uploading oversized images * **Too many items** — Order with extremely many line items * **Server limits** — PHP or web server has low upload limits ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Reduce Request Size[​](#1-reduce-request-size "Direct link to 1. Reduce Request Size") If syncing data: * Try syncing in smaller batches * The POS should handle this automatically * Wait for current sync to complete before starting another ### 2. Check Image Sizes[​](#2-check-image-sizes "Direct link to 2. Check Image Sizes") If uploading images: * Resize images before uploading * Use compressed formats (JPEG vs BMP) * Most product images work well under 1MB ### 3. Split Large Orders[​](#3-split-large-orders "Direct link to 3. Split Large Orders") If an order has many items: * Consider splitting into multiple orders * This is rare in normal POS usage ### 4. Increase Server Limits[​](#4-increase-server-limits "Direct link to 4. Increase Server Limits") Contact your hosting provider or edit PHP settings: ``` // In php.ini or .htaccess upload_max_filesize = 64M post_max_size = 64M max_input_vars = 5000 ``` ### 5. Check Web Server Limits[​](#5-check-web-server-limits "Direct link to 5. Check Web Server Limits") Nginx or Apache may have their own limits: * `client_max_body_size` for Nginx * `LimitRequestBody` for Apache ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API03005](/error-codes/API03005.md) — Rate Limit Exceeded * [API03007](/error-codes/API03007.md) — Request Queue Full --- # API03005: Rate Limit Exceeded ## What This Means[​](#what-this-means "Direct link to What This Means") You've made too many requests to the server in a short period. Rate limiting protects the server from being overwhelmed. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Rapid sync operations** — Multiple devices syncing simultaneously * **Aggressive refresh** — Refreshing data too frequently * **Security plugin** — A plugin is enforcing request limits * **Hosting limits** — Your hosting plan has API rate limits ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | ----------- | ------------------------------ | | HTTP 429 | Any server response (fallback) | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Wait and Retry[​](#1-wait-and-retry "Direct link to 1. Wait and Retry") Rate limits are temporary: * Wait 1-5 minutes * The POS will automatically retry * Avoid manually refreshing repeatedly ### 2. Reduce Concurrent Operations[​](#2-reduce-concurrent-operations "Direct link to 2. Reduce Concurrent Operations") If using multiple POS terminals: * Stagger initial sync across devices * Avoid refreshing all devices at once * Let one complete before starting another ### 3. Check Security Plugins[​](#3-check-security-plugins "Direct link to 3. Check Security Plugins") Plugins like Wordfence may block rapid requests: * Whitelist the POS application * Whitelist your POS device IPs * Adjust rate limiting thresholds ### 4. Review Hosting Limits[​](#4-review-hosting-limits "Direct link to 4. Review Hosting Limits") Some hosts limit API requests: * Check your hosting plan details * Consider upgrading if limits are too low * Contact support about increasing limits ### 5. Optimise Sync Frequency[​](#5-optimise-sync-frequency "Direct link to 5. Optimise Sync Frequency") In POS settings: * Adjust auto-refresh intervals * Use manual sync when appropriate * Avoid unnecessary data refreshes ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API03004](/error-codes/API03004.md) — Request Too Large * [API03007](/error-codes/API03007.md) — Request Queue Full --- # API03006: Unsupported Method ## What This Means[​](#what-this-means "Direct link to What This Means") The HTTP method used (GET, POST, PUT, DELETE, etc.) is not supported for this endpoint. The server doesn't accept this type of request for this URL. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Version mismatch** — POS and plugin versions are incompatible * **Endpoint removed** — An API endpoint was deprecated * **Server configuration** — Web server blocking certain HTTP methods * **Plugin conflict** — Another plugin modifying REST API behaviour ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Update Both Components[​](#1-update-both-components "Direct link to 1. Update Both Components") Ensure compatibility: * Update the WCPOS WordPress plugin * Update the POS application * Check release notes for breaking changes ### 2. Check Server Configuration[​](#2-check-server-configuration "Direct link to 2. Check Server Configuration") Some servers block certain HTTP methods: * Ensure PUT and DELETE methods are allowed * Check `.htaccess` for method restrictions * Review Nginx configuration ### 3. Verify REST API Access[​](#3-verify-rest-api-access "Direct link to 3. Verify REST API Access") Test the WordPress REST API: 1. Visit `https://yoursite.com/wp-json/` in a browser 2. It should return JSON data 3. If not, the REST API may be disabled or blocked ### 4. Check for Plugin Conflicts[​](#4-check-for-plugin-conflicts "Direct link to 4. Check for Plugin Conflicts") Disable other plugins temporarily: * Security plugins may block methods * Other REST API plugins may cause conflicts * Re-enable one by one to find the issue ### 5. Review Hosting Restrictions[​](#5-review-hosting-restrictions "Direct link to 5. Review Hosting Restrictions") Some hosts restrict HTTP methods: * Contact hosting support * Request they enable all standard methods * Consider switching hosts if too restrictive ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API03001](/error-codes/API03001.md) — Invalid Request Format * [API05004](/error-codes/API05004.md) — WordPress API Disabled --- # API03007: Request Queue Full ## What This Means[​](#what-this-means "Direct link to What This Means") The POS has too many pending requests waiting to be sent. The internal queue is full and cannot accept more requests until some complete. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Slow network** — Requests backing up due to slow connection * **Server unresponsive** — Server taking too long to respond * **Rapid actions** — Performing many actions faster than they can process * **Sync overload** — Large sync operation blocking the queue ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Wait for Queue to Clear[​](#1-wait-for-queue-to-clear "Direct link to 1. Wait for Queue to Clear") Give pending requests time to complete: * Wait 30-60 seconds * Watch for sync indicators to complete * Avoid additional actions until cleared ### 2. Check Network Connection[​](#2-check-network-connection "Direct link to 2. Check Network Connection") A slow connection causes backup: * Test your internet speed * Try a faster connection * Move closer to WiFi router ### 3. Check Server Response Time[​](#3-check-server-response-time "Direct link to 3. Check Server Response Time") If the server is slow: * Test accessing your site in a browser * Contact hosting if site is slow * Wait for server load to decrease ### 4. Restart the POS[​](#4-restart-the-pos "Direct link to 4. Restart the POS") If the queue is stuck: 1. Close the POS application 2. Wait a moment 3. Reopen the POS 4. Pending requests may need to be re-initiated ### 5. Avoid Rapid Actions[​](#5-avoid-rapid-actions "Direct link to 5. Avoid Rapid Actions") During sync or slow periods: * Wait for one action to complete before starting another * Don't repeatedly click buttons * Be patient with network operations ## Offline Behaviour[​](#offline-behaviour "Direct link to Offline Behaviour") When the queue fills due to offline conditions: * The POS will hold pending requests until back online * You can still browse cached products and customers * You can start new orders and add items to the cart * Completing orders requires connectivity to be restored ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API03004](/error-codes/API03004.md) — Request Too Large * [API03005](/error-codes/API03005.md) — Rate Limit Exceeded --- # API04001: Invalid Response Format ## What This Means[​](#what-this-means "Direct link to What This Means") The server responded, but the response format is not what the POS expected. The server should return JSON data, but something else was received. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **PHP error displayed** — A PHP error is being output before JSON * **Plugin conflict** — Another plugin is outputting content * **Maintenance mode** — Site is showing a maintenance page * **Wrong content type** — Server sending HTML instead of JSON * **Caching issue** — A cached error page is being served ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check Your Site[​](#1-check-your-site "Direct link to 1. Check Your Site") Visit your WordPress site in a browser: * Is it displaying normally? * Are there any visible errors? * Is it in maintenance mode? ### 2. Check for PHP Errors[​](#2-check-for-php-errors "Direct link to 2. Check for PHP Errors") In `wp-config.php`, temporarily enable debugging: ``` define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); define('WP_DEBUG_DISPLAY', false); ``` Check `wp-content/debug.log` for errors. ### 3. Test the REST API Directly[​](#3-test-the-rest-api-directly "Direct link to 3. Test the REST API Directly") Visit `https://yoursite.com/wp-json/` in your browser: * Should return JSON data * If you see HTML or errors, there's a problem * Check for plugin-related output ### 4. Disable Caching Temporarily[​](#4-disable-caching-temporarily "Direct link to 4. Disable Caching Temporarily") Caching plugins may serve stale responses: * Clear all caches * Temporarily disable caching plugins * Exclude the REST API from caching ### 5. Check for Plugin Conflicts[​](#5-check-for-plugin-conflicts "Direct link to 5. Check for Plugin Conflicts") If a plugin outputs content on every page: 1. Disable all non-essential plugins 2. Test the POS 3. Re-enable plugins one by one ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API04003](/error-codes/API04003.md) — Malformed JSON Response * [API05005](/error-codes/API05005.md) — Plugin Not Found --- # API04002: Unexpected Response Code ## What This Means[​](#what-this-means "Direct link to What This Means") The server returned an HTTP status code that wasn't expected for this request. Common codes include 500 (server error), 403 (forbidden), 404 (not found), etc. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **500 Internal Server Error** — PHP crashed or encountered an error * **403 Forbidden** — Access denied by security settings * **404 Not Found** — The endpoint doesn't exist * **502/503/504** — Server gateway or availability issues ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### For 500 Errors (Server Error)[​](#for-500-errors-server-error "Direct link to For 500 Errors (Server Error)") 1. Check PHP error logs 2. Increase PHP memory limit 3. Look for plugin conflicts 4. Check `wp-content/debug.log` ### For 403 Errors (Forbidden)[​](#for-403-errors-forbidden "Direct link to For 403 Errors (Forbidden)") 1. Check security plugin settings (Wordfence, Sucuri, etc.) 2. Whitelist the POS or your IP 3. Check `.htaccess` for blocking rules 4. Verify ModSecurity isn't blocking requests ### For 404 Errors (Not Found)[​](#for-404-errors-not-found "Direct link to For 404 Errors (Not Found)") 1. Verify the WCPOS plugin is active 2. Flush WordPress permalinks (Settings → Permalinks → Save) 3. Check if REST API is enabled 4. Verify URL configuration ### For 502/503/504 Errors (Gateway Issues)[​](#for-502503504-errors-gateway-issues "Direct link to For 502/503/504 Errors (Gateway Issues)") 1. Contact your hosting provider 2. Wait for server to recover 3. Check if site is under heavy load 4. Verify server is running ### General Troubleshooting[​](#general-troubleshooting "Direct link to General Troubleshooting") 1. Try accessing your site directly 2. Check hosting control panel for issues 3. Review server access logs 4. Contact hosting support if needed ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API04001](/error-codes/API04001.md) — Invalid Response Format * [API01008](/error-codes/API01008.md) — Website Unavailable --- # API04003: Malformed JSON Response ## What This Means[​](#what-this-means "Direct link to What This Means") The server returned data that appears to be JSON but is corrupted or invalid. The POS couldn't parse the response because the JSON syntax is broken. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **PHP notices/warnings** — PHP output before the JSON * **BOM (Byte Order Mark)** — Invisible characters at file start * **Encoding issues** — Character encoding problems * **Truncated response** — Response cut off mid-transmission * **Plugin output** — A plugin added non-JSON content ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check for PHP Notices[​](#1-check-for-php-notices "Direct link to 1. Check for PHP Notices") PHP notices/warnings before JSON break parsing: In `wp-config.php`: ``` define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); define('WP_DEBUG_DISPLAY', false); ``` Review `wp-content/debug.log` and fix any issues. ### 2. Check for BOM Characters[​](#2-check-for-bom-characters "Direct link to 2. Check for BOM Characters") Some text editors add invisible BOM characters: * Re-save PHP files without BOM * Use UTF-8 without BOM encoding * Check recently edited files ### 3. Verify Complete Response[​](#3-verify-complete-response "Direct link to 3. Verify Complete Response") If responses are being truncated: * Check PHP output buffering settings * Increase `output_buffering` in php.ini * Check for timeout issues ### 4. Test API Directly[​](#4-test-api-directly "Direct link to 4. Test API Directly") In your browser or using curl: ``` curl -v https://yoursite.com/wp-json/wcpos/v1/ ``` Look for any unexpected content before the JSON. ### 5. Check Character Encoding[​](#5-check-character-encoding "Direct link to 5. Check Character Encoding") Ensure database and PHP use UTF-8: * Check `wp-config.php` charset settings * Verify database tables are UTF-8 * Look for special characters causing issues ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API04001](/error-codes/API04001.md) — Invalid Response Format * [API04005](/error-codes/API04005.md) — JSON Recovery Attempted --- # API04004: Missing Response Data ## What This Means[​](#what-this-means "Direct link to What This Means") The server responded successfully, but the response is missing expected data. The JSON is valid but doesn't contain the information the POS needs. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Empty results** — No data matches the query * **Permission restrictions** — Data filtered due to permissions * **Plugin filtering** — Another plugin filtering API responses * **Version mismatch** — API version differences * **Database issues** — Data not present in WooCommerce ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Verify Data Exists[​](#1-verify-data-exists "Direct link to 1. Verify Data Exists") Check in WordPress Admin: * Are there products in WooCommerce? * Are there customers to load? * Does the specific item exist? ### 2. Check User Permissions[​](#2-check-user-permissions "Direct link to 2. Check User Permissions") Your user may not have access to all data: * Verify user role capabilities * Check POS access settings * Try with an administrator account ### 3. Check API Response Filters[​](#3-check-api-response-filters "Direct link to 3. Check API Response Filters") Some plugins filter REST API responses: * Disable filtering plugins temporarily * Check for custom API filters in your theme * Review security plugin settings ### 4. Update Both Components[​](#4-update-both-components "Direct link to 4. Update Both Components") Version mismatches can cause issues: * Update WCPOS plugin * Update the POS application * Check for compatibility notes ### 5. Check WooCommerce Data[​](#5-check-woocommerce-data "Direct link to 5. Check WooCommerce Data") In WooCommerce: * Verify products are published (not draft) * Check if items are marked as visible * Ensure data isn't corrupted ## Empty vs. Missing[​](#empty-vs-missing "Direct link to Empty vs. Missing") * **Empty response** — Valid response with no results (may be expected) * **Missing fields** — Response lacks required data fields (this error) ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API04001](/error-codes/API04001.md) — Invalid Response Format * [API02004](/error-codes/API02004.md) — User Not Authorized --- # API04005: JSON Recovery Attempted ## What This Means[​](#what-this-means "Direct link to What This Means") The server sent a response with some invalid JSON content, but the POS attempted to recover and extract valid data. This is an informational notice rather than a critical error. ## What Happened[​](#what-happened "Direct link to What Happened") The POS detected: 1. The response contained extra content before or after the JSON 2. The core JSON data was still identifiable 3. Recovery was attempted by extracting the valid JSON portion ## Common Causes[​](#common-causes "Direct link to Common Causes") * **PHP notices in output** — PHP warnings mixed with JSON * **Debug output** — Development debugging left enabled * **Plugin notices** — Other plugins outputting notices * **Whitespace issues** — Extra whitespace around JSON ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Disable PHP Display Errors[​](#1-disable-php-display-errors "Direct link to 1. Disable PHP Display Errors") In `wp-config.php`: ``` define('WP_DEBUG_DISPLAY', false); ini_set('display_errors', 0); ``` ### 2. Enable Error Logging Instead[​](#2-enable-error-logging-instead "Direct link to 2. Enable Error Logging Instead") Keep errors logged for debugging: ``` define('WP_DEBUG', true); define('WP_DEBUG_LOG', true); ``` ### 3. Check for Plugin Debug Mode[​](#3-check-for-plugin-debug-mode "Direct link to 3. Check for Plugin Debug Mode") Some plugins have debug modes that output extra content: * Review plugin settings * Disable debug/development modes * Check for verbose logging options ### 4. Review Recent Changes[​](#4-review-recent-changes "Direct link to 4. Review Recent Changes") If this started recently: * What changed on your server? * Were plugins updated? * Were PHP settings modified? ## Is This Serious?[​](#is-this-serious "Direct link to Is This Serious?") While the POS recovered from this issue, it indicates a configuration problem that should be fixed. The recovery process: * May not always work * Adds processing overhead * Could mask other issues Fix the underlying cause to ensure reliable operation. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API04003](/error-codes/API04003.md) — Malformed JSON Response * [API04001](/error-codes/API04001.md) — Invalid Response Format --- # API04006: Resource Not Found ## What This Means[​](#what-this-means "Direct link to What This Means") The server could not find the requested resource. This typically corresponds to an HTTP 404 status code, indicating the product, order, customer, or other resource you're trying to access doesn't exist. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Record deleted** — The resource was deleted on the server * **Wrong ID** — An incorrect or outdated ID is being used * **Sync issues** — Local data references a resource that no longer exists * **URL misconfiguration** — The API endpoint is incorrect * **Permalink issues** — WordPress permalinks need to be refreshed ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | --------------- | ------------------- | | `rest_no_route` | WordPress REST API | | HTTP 404 | Any server response | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check if the Resource Exists[​](#1-check-if-the-resource-exists "Direct link to 1. Check if the Resource Exists") Verify the resource still exists on your WooCommerce site: * Log into WordPress admin * Navigate to the relevant section (Products, Orders, Customers) * Search for the item by ID or name ### 2. Refresh Local Data[​](#2-refresh-local-data "Direct link to 2. Refresh Local Data") If the resource was deleted server-side: 1. Open the POS settings 2. Navigate to the relevant data section 3. Trigger a sync/refresh to update local data 4. The deleted item should be removed locally ### 3. Check WordPress Permalinks[​](#3-check-wordpress-permalinks "Direct link to 3. Check WordPress Permalinks") If multiple resources are not found: 1. Go to **Settings → Permalinks** in WordPress admin 2. Click **Save Changes** (even without making changes) 3. This refreshes the permalink structure ### 4. Verify API Routes[​](#4-verify-api-routes "Direct link to 4. Verify API Routes") Test the REST API directly: ``` https://yoursite.com/wp-json/wc/v3/products ``` If this returns a 404, there may be a server configuration issue. ### 5. Check for Plugin Conflicts[​](#5-check-for-plugin-conflicts "Direct link to 5. Check for Plugin Conflicts") If REST API routes are missing: 1. Ensure WooCommerce is active 2. Ensure WCPOS plugin is active 3. Disable other plugins temporarily to test ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API04001](/error-codes/API04001.md) — Invalid Response Format * [API04002](/error-codes/API04002.md) — Unexpected Response Code * [API05002](/error-codes/API05002.md) — WCPOS Plugin Not Found --- # API05001: WooCommerce API Disabled ## What This Means[​](#what-this-means "Direct link to What This Means") The WooCommerce REST API is disabled on your site. WCPOS requires the REST API to communicate with WooCommerce and access store data. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **WooCommerce setting** — The REST API was intentionally disabled * **Security plugin** — A security plugin is blocking API access * **Hosting restriction** — Your host has disabled REST API access * **Permalink issues** — Permalinks not configured for REST API ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Enable WooCommerce REST API[​](#1-enable-woocommerce-rest-api "Direct link to 1. Enable WooCommerce REST API") In WordPress Admin: 1. Go to WooCommerce → Settings → Advanced → REST API 2. Ensure the REST API is enabled 3. Verify API keys are created ### 2. Check WordPress REST API[​](#2-check-wordpress-rest-api "Direct link to 2. Check WordPress REST API") The WooCommerce API depends on WordPress REST API: 1. Visit `https://yoursite.com/wp-json/` in your browser 2. Should return JSON data 3. If not, see [API05004](/error-codes/API05004.md) ### 3. Check Security Plugins[​](#3-check-security-plugins "Direct link to 3. Check Security Plugins") Common security plugins that may block the API: * **Wordfence** — Check firewall settings * **iThemes Security** — Check REST API settings * **All In One WP Security** — Review firewall rules Whitelist REST API endpoints or the POS application. ### 4. Check .htaccess[​](#4-check-htaccess "Direct link to 4. Check .htaccess") Look for rules blocking API access: ``` # Remove or modify rules blocking /wp-json/ # Ensure mod_rewrite is enabled ``` ### 5. Flush Permalinks[​](#5-flush-permalinks "Direct link to 5. Flush Permalinks") Sometimes permalink settings need refreshing: 1. Go to Settings → Permalinks 2. Click "Save Changes" (even without making changes) 3. This regenerates rewrite rules ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API05004](/error-codes/API05004.md) — WordPress API Disabled * [API02006](/error-codes/API02006.md) — API Key Invalid --- # API05002: WCPOS Plugin Not Found ## What This Means[​](#what-this-means "Direct link to What This Means") The WCPOS plugin is not installed or not active on your WordPress site. The POS application requires this plugin to communicate with WooCommerce. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Plugin not installed** — The plugin was never installed * **Plugin deactivated** — The plugin was disabled * **Plugin deleted** — The plugin files were removed * **Wrong site** — Connected to a site without WCPOS ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Install the Plugin[​](#1-install-the-plugin "Direct link to 1. Install the Plugin") If not installed: 1. Go to WordPress Admin → Plugins → Add New 2. Search for "WooCommerce POS" 3. Install and activate the plugin Or download from [WordPress.org](https://wordpress.org/plugins/woocommerce-pos/) ### 2. Activate the Plugin[​](#2-activate-the-plugin "Direct link to 2. Activate the Plugin") If installed but not active: 1. Go to Plugins → Installed Plugins 2. Find "WooCommerce POS" 3. Click "Activate" ### 3. Check for Errors[​](#3-check-for-errors "Direct link to 3. Check for Errors") If the plugin won't activate: * Check for PHP errors in your error log * Verify WooCommerce is installed and active * Check PHP version requirements * Look for plugin conflicts ### 4. Verify the URL[​](#4-verify-the-url "Direct link to 4. Verify the URL") Ensure the POS is configured to connect to the correct WordPress site: * Check the URL in POS settings * Verify it matches your WordPress installation ### 5. Reinstall if Necessary[​](#5-reinstall-if-necessary "Direct link to 5. Reinstall if Necessary") If the plugin is corrupted: 1. Deactivate and delete the plugin 2. Reinstall from WordPress.org 3. Activate the plugin ## Requirements[​](#requirements "Direct link to Requirements") WordPress : Recent version WooCommerce : Recent version PHP : Version 7.4 or higher ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API05003](/error-codes/API05003.md) — WCPOS Plugin Outdated * [API05005](/error-codes/API05005.md) — Plugin Not Found --- # API05003: WCPOS Plugin Outdated ## What This Means[​](#what-this-means "Direct link to What This Means") The WCPOS plugin installed on your server is outdated and not compatible with your version of the POS application. You need to update the plugin. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Plugin not updated** — Auto-updates may be disabled * **Update failed** — A previous update attempt failed * **Version mismatch** — POS app updated but plugin wasn't * **Staging/dev site** — Testing on an older version ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Update the Plugin[​](#1-update-the-plugin "Direct link to 1. Update the Plugin") In WordPress Admin: 1. Go to Plugins → Installed Plugins 2. Find "WooCommerce POS" 3. If an update is available, click "Update Now" ### 2. Enable Auto-Updates[​](#2-enable-auto-updates "Direct link to 2. Enable Auto-Updates") To prevent future mismatches: 1. Go to Plugins → Installed Plugins 2. Find "WooCommerce POS" 3. Click "Enable auto-updates" ### 3. Manual Update[​](#3-manual-update "Direct link to 3. Manual Update") If automatic update fails: 1. Download the latest version from [WordPress.org](https://wordpress.org/plugins/woocommerce-pos/) 2. Deactivate the current plugin 3. Delete the old plugin files 4. Upload and activate the new version ### 4. Check for Update Errors[​](#4-check-for-update-errors "Direct link to 4. Check for Update Errors") If updates are failing: * Check file permissions on wp-content/plugins * Verify you have disk space * Look for PHP memory issues * Check error logs for details ### 5. Downgrade POS App (Temporary)[​](#5-downgrade-pos-app-temporary "Direct link to 5. Downgrade POS App (Temporary)") If you can't update the plugin immediately: * Use an older version of the POS app * This is a temporary workaround only * Plan to update the plugin soon ## Version Compatibility[​](#version-compatibility "Direct link to Version Compatibility") Always keep both components updated: * The POS application * The WCPOS WordPress plugin Check release notes for any breaking changes when updating. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API05002](/error-codes/API05002.md) — WCPOS Plugin Not Found * [API05005](/error-codes/API05005.md) — Plugin Not Found --- # API05004: WordPress API Disabled ## What This Means[​](#what-this-means "Direct link to What This Means") The WordPress REST API is disabled on your site. All modern WordPress functionality, including WooCommerce and WCPOS, depends on this API. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Security plugin** — A plugin is blocking REST API access * **Hosting restriction** — Your host disabled the REST API * **Custom code** — A theme or plugin disabled the API * **Firewall rules** — WAF blocking REST API endpoints ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Test the REST API[​](#1-test-the-rest-api "Direct link to 1. Test the REST API") Visit `https://yoursite.com/wp-json/` in your browser: * Should return JSON with available routes * If you get an error or nothing, it's blocked ### 2. Check Security Plugins[​](#2-check-security-plugins "Direct link to 2. Check Security Plugins") Common plugins that block REST API: **Wordfence:** * Firewall → All Firewall Options * Disable "Disable REST API" option **iThemes Security:** * Security → Settings → WordPress Tweaks * Enable REST API **Disable REST API Plugin:** * Deactivate this plugin entirely ### 3. Check for Custom Code[​](#3-check-for-custom-code "Direct link to 3. Check for Custom Code") Look in your theme's `functions.php` or custom plugins for: ``` // This code disables REST API - remove it add_filter('rest_authentication_errors', function($result) { return new WP_Error('rest_disabled', 'REST API disabled'); }); ``` ### 4. Check .htaccess[​](#4-check-htaccess "Direct link to 4. Check .htaccess") Remove any rules blocking `/wp-json/`: ``` # Bad - blocks REST API RewriteRule ^wp-json - [F,L] ``` ### 5. Contact Hosting Provider[​](#5-contact-hosting-provider "Direct link to 5. Contact Hosting Provider") Some hosts block REST API by default: * Request they enable it * Ask about any security restrictions * Check hosting documentation ## Why REST API Matters[​](#why-rest-api-matters "Direct link to Why REST API Matters") The WordPress REST API is essential for: * Mobile apps * Third-party integrations * WooCommerce functions * WCPOS operation Disabling it breaks many features. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API05001](/error-codes/API05001.md) — WooCommerce API Disabled * [API03006](/error-codes/API03006.md) — Unsupported Method --- # API05005: Plugin Not Found ## What This Means[​](#what-this-means "Direct link to What This Means") A required WordPress plugin is not installed or active. This could be WooCommerce itself, a required extension, or an integration plugin. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **WooCommerce deactivated** — WooCommerce was disabled * **Required extension missing** — A needed WooCommerce extension isn't installed * **Plugin conflict** — Another plugin caused a required plugin to deactivate * **Failed update** — A plugin update failed and left it deactivated ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Verify WooCommerce is Active[​](#1-verify-woocommerce-is-active "Direct link to 1. Verify WooCommerce is Active") WCPOS requires WooCommerce: 1. Go to Plugins → Installed Plugins 2. Find "WooCommerce" 3. Ensure it's activated ### 2. Check for Required Extensions[​](#2-check-for-required-extensions "Direct link to 2. Check for Required Extensions") Some WCPOS features may require extensions: * Check error message for specific plugin name * Install and activate the required extension ### 3. Review Plugin Conflicts[​](#3-review-plugin-conflicts "Direct link to 3. Review Plugin Conflicts") If plugins were deactivated due to conflicts: 1. Check your email for WordPress notifications 2. Review error logs 3. Resolve conflicts and reactivate ### 4. Check Plugin Files[​](#4-check-plugin-files "Direct link to 4. Check Plugin Files") If a plugin's files are missing: 1. Reinstall the plugin from WordPress.org 2. Or restore from backup 3. Activate the plugin ### 5. Update All Plugins[​](#5-update-all-plugins "Direct link to 5. Update All Plugins") Outdated plugins may cause issues: 1. Go to Dashboard → Updates 2. Update all plugins 3. Verify all required plugins are active ## Required Plugins[​](#required-plugins "Direct link to Required Plugins") At minimum, WCPOS requires: * **WooCommerce** — The e-commerce platform * **WCPOS** — The POS plugin Additional features may require other plugins. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API05002](/error-codes/API05002.md) — WCPOS Plugin Not Found * [API05001](/error-codes/API05001.md) — WooCommerce API Disabled --- # API06001: Invalid URL Format ## What This Means[​](#what-this-means "Direct link to What This Means") The URL configured for your WooCommerce site is not in a valid format. URLs must follow standard web address conventions. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Missing protocol** — URL doesn't start with `http://` or `https://` * **Typo in URL** — Spelling errors in the domain * **Invalid characters** — Special characters that aren't allowed in URLs * **Incomplete URL** — URL is missing parts like the domain extension ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check URL Format[​](#1-check-url-format "Direct link to 1. Check URL Format") A valid URL should look like: * ✅ `https://yourstore.com` * ✅ `https://www.yourstore.com` * ✅ `https://store.yourdomain.com` * ❌ `yourstore.com` (missing protocol) * ❌ `https://yourstore` (missing extension) * ❌ `https://your store.com` (contains space) ### 2. Include the Protocol[​](#2-include-the-protocol "Direct link to 2. Include the Protocol") Always include `https://` or `http://`: * Preferred: `https://` (secure) * Fallback: `http://` (if HTTPS isn't available) ### 3. Remove Extra Characters[​](#3-remove-extra-characters "Direct link to 3. Remove Extra Characters") Ensure the URL doesn't have: * Trailing slashes (optional but be consistent) * Extra spaces * Special characters * URL parameters (unless required) ### 4. Verify the URL Works[​](#4-verify-the-url-works "Direct link to 4. Verify the URL Works") Test the URL in a browser: 1. Copy the URL you're using 2. Paste it in a browser 3. It should load your WordPress site ### 5. Update POS Configuration[​](#5-update-pos-configuration "Direct link to 5. Update POS Configuration") Enter the corrected URL in the POS settings: * Match exactly what works in your browser * Include or exclude `www.` as your site uses ## Examples[​](#examples "Direct link to Examples") | Invalid | Valid | | ---------------------- | --------------------- | | `mystore.com` | `https://mystore.com` | | `https://my store.com` | `https://mystore.com` | | `https://mystore` | `https://mystore.com` | | `htp://mystore.com` | `https://mystore.com` | ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API06002](/error-codes/API06002.md) — Missing API URL * [API01004](/error-codes/API01004.md) — DNS Resolution Failed --- # API06002: Missing API URL ## What This Means[​](#what-this-means "Direct link to What This Means") No URL has been configured for connecting to your WooCommerce store. The POS needs to know where your store is located. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **First-time setup** — URL was never entered * **Configuration cleared** — Settings were reset or cleared * **App data cleared** — Application data was deleted * **Migration issue** — URL lost during update or migration ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Enter Your Store URL[​](#1-enter-your-store-url "Direct link to 1. Enter Your Store URL") In the POS app: 1. Open settings or login screen 2. Find the URL/Site configuration field 3. Enter your WordPress site URL 4. Example: `https://yourstore.com` ### 2. Find Your WordPress URL[​](#2-find-your-wordpress-url "Direct link to 2. Find Your WordPress URL") If you're unsure of your URL: 1. Log into WordPress Admin 2. Go to Settings → General 3. Look at "WordPress Address (URL)" 4. Use this URL in the POS ### 3. Check Stored Settings[​](#3-check-stored-settings "Direct link to 3. Check Stored Settings") If the URL was previously configured: * Check if app data was accidentally cleared * Look for settings backup/export options * Re-enter the URL if needed ### 4. Verify URL is Correct[​](#4-verify-url-is-correct "Direct link to 4. Verify URL is Correct") Before saving: 1. Test the URL in a browser 2. Ensure it loads your WordPress site 3. Include `https://` or `http://` ## Setup Checklist[​](#setup-checklist "Direct link to Setup Checklist") When configuring WCPOS for the first time: 1. ☐ Enter your WordPress site URL 2. ☐ Verify WCPOS plugin is installed and active 3. ☐ Login with your WordPress credentials 4. ☐ Allow initial data sync to complete ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API06001](/error-codes/API06001.md) — Invalid URL Format * [API06003](/error-codes/API06003.md) — Invalid Site Configuration --- # API06003: Invalid Site Configuration ## What This Means[​](#what-this-means "Direct link to What This Means") The site configuration is invalid or incomplete. This could involve incorrect URLs, authentication settings, or other configuration issues. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Partial configuration** — Some settings are missing * **Mismatched settings** — Configuration doesn't match the site * **Corrupted configuration** — Settings were corrupted * **Site changes** — The site was modified without updating POS config ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Review All Settings[​](#1-review-all-settings "Direct link to 1. Review All Settings") Check the complete configuration: * Site URL is correct * Authentication is properly configured * Any additional settings are correct ### 2. Reconfigure from Scratch[​](#2-reconfigure-from-scratch "Direct link to 2. Reconfigure from Scratch") If configuration is corrupted: 1. Clear all stored settings 2. Start the setup process again 3. Enter fresh configuration ### 3. Check Site Requirements[​](#3-check-site-requirements "Direct link to 3. Check Site Requirements") Verify your WordPress site meets requirements: * WordPress is installed and accessible * WooCommerce is installed and active * WCPOS plugin is installed and active * Permalinks are enabled (not "Plain") ### 4. Test Site Access[​](#4-test-site-access "Direct link to 4. Test Site Access") Verify these URLs work in a browser: * `https://yoursite.com/` — Main site * `https://yoursite.com/wp-json/` — REST API * `https://yoursite.com/wp-json/wcpos/v1/` — WCPOS API ### 5. Check WordPress Settings[​](#5-check-wordpress-settings "Direct link to 5. Check WordPress Settings") In WordPress Admin: 1. Settings → General — Verify URLs 2. Settings → Permalinks — Ensure not "Plain" 3. WooCommerce → Status — Check for issues ## Configuration Requirements[​](#configuration-requirements "Direct link to Configuration Requirements") A valid configuration needs: * **Site URL** — Full URL with protocol * **Authentication** — Valid credentials or API keys * **Permissions** — User has POS access * **Plugins** — Required plugins are active ## Related Errors[​](#related-errors "Direct link to Related Errors") * [API06001](/error-codes/API06001.md) — Invalid URL Format * [API06002](/error-codes/API06002.md) — Missing API URL * [API05002](/error-codes/API05002.md) — WCPOS Plugin Not Found --- # Database Errors Database errors occur when storing or retrieving data in the local database. WCPOS uses a local database to store products, customers, and other data for fast access and offline functionality. These errors are prefixed with `DB`. ## Categories[​](#categories "Direct link to Categories") | Category | Code Range | Description | | -------------------------------- | ---------- | ------------------------------------------ | | [Connection](#connection-errors) | DB01xxx | Database connection and transaction issues | | [Data](#data-errors) | DB02xxx | Record and constraint issues | | [Query](#query-errors) | DB03xxx | Query syntax and data type issues | *** ## Connection Errors[​](#connection-errors "Direct link to Connection Errors") Issues connecting to or operating on the local database. | Code | Name | Description | | ---------------------------------- | ------------------ | --------------------------------------- | | [DB01001](/error-codes/DB01001.md) | Connection Failed | Could not connect to the local database | | [DB01002](/error-codes/DB01002.md) | Query Timeout | Database query took too long | | [DB01003](/error-codes/DB01003.md) | Transaction Failed | Database transaction could not complete | ## Data Errors[​](#data-errors "Direct link to Data Errors") Issues with records, duplicates, and constraints. | Code | Name | Description | | ---------------------------------- | -------------------- | ------------------------------------ | | [DB02001](/error-codes/DB02001.md) | Duplicate Record | A record with this ID already exists | | [DB02002](/error-codes/DB02002.md) | Record Not Found | The requested record does not exist | | [DB02003](/error-codes/DB02003.md) | Constraint Violation | Data violates database constraints | ## Query Errors[​](#query-errors "Direct link to Query Errors") Issues with query syntax and data types. | Code | Name | Description | | ---------------------------------- | ---------------------- | -------------------------------------- | | [DB03001](/error-codes/DB03001.md) | Query Syntax Error | The database query has syntax errors | | [DB03002](/error-codes/DB03002.md) | Invalid Data Type | Data type does not match expected type | | [DB03003](/error-codes/DB03003.md) | Missing Required Field | A required field is empty | --- # DB01001: Connection Failed ## What This Means[​](#what-this-means "Direct link to What This Means") The POS could not connect to its local database. WCPOS uses a local database to store products, customers, and other data for fast access and offline functionality. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Storage full** — Device has no storage space left * **Database corrupted** — Local database files are damaged * **Permission issue** — App doesn't have storage permissions * **Browser storage disabled** — IndexedDB is disabled (web version) ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check Storage Space[​](#1-check-storage-space "Direct link to 1. Check Storage Space") Ensure your device has available storage: * Free up space if storage is full * Delete unused apps or files * Check available disk space ### 2. Clear App Data[​](#2-clear-app-data "Direct link to 2. Clear App Data") Reset the local database: * **Desktop app:** Look for "Clear Data" in settings * **Web browser:** Clear site data for the POS domain * **Note:** This will require re-syncing all data ### 3. Check Browser Settings (Web)[​](#3-check-browser-settings-web "Direct link to 3. Check Browser Settings (Web)") If using the web version: 1. Ensure IndexedDB is enabled 2. Don't use private/incognito mode (limited storage) 3. Allow the site to store data ### 4. Check Permissions[​](#4-check-permissions "Direct link to 4. Check Permissions") On desktop: * Ensure the app has permission to write to its data directory * Check if antivirus is blocking database access ### 5. Reinstall the App[​](#5-reinstall-the-app "Direct link to 5. Reinstall the App") If other solutions fail: 1. Uninstall the POS app 2. Restart your device 3. Reinstall the app 4. Login and sync data ## Data Recovery[​](#data-recovery "Direct link to Data Recovery") If you have unsaved data: * The app may have pending changes that couldn't be synced * Contact support if you need help recovering data * In most cases, data can be re-synced from the server ## Related Errors[​](#related-errors "Direct link to Related Errors") * [DB01002](/error-codes/DB01002.md) — Query Timeout * [SY01002](/error-codes/SY01002.md) — Disk Full --- # DB01002: Query Timeout ## What This Means[​](#what-this-means "Direct link to What This Means") A database operation took too long to complete. The local database query exceeded the maximum allowed time. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Large data set** — Very large number of products or records * **Complex query** — Query involving many conditions * **Device performance** — Device is running slowly * **Database fragmentation** — Database needs optimisation ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Wait and Retry[​](#1-wait-and-retry "Direct link to 1. Wait and Retry") The query may succeed on retry: * Close and reopen the POS * Try the operation again * Avoid other intensive operations simultaneously ### 2. Close Other Applications[​](#2-close-other-applications "Direct link to 2. Close Other Applications") Free up device resources: * Close unused browser tabs * Close other applications * Restart the device if needed ### 3. Reduce Data Scope[​](#3-reduce-data-scope "Direct link to 3. Reduce Data Scope") If searching: * Use more specific search terms * Apply filters to narrow results * Break large operations into smaller ones ### 4. Optimise the Database[​](#4-optimise-the-database "Direct link to 4. Optimise the Database") Clear and re-sync: 1. Clear local data (settings option if available) 2. Login again 3. Let data sync fresh ### 5. Check Device Performance[​](#5-check-device-performance "Direct link to 5. Check Device Performance") Ensure your device meets requirements: * Sufficient RAM * Adequate processor speed * SSD preferred over HDD ## Large Catalogues[​](#large-catalogues "Direct link to Large Catalogues") If you have a very large product catalogue: * Initial sync takes longer * Consider using filters in the POS * Some operations naturally take more time * Contact support for optimisation advice ## Related Errors[​](#related-errors "Direct link to Related Errors") * [DB01001](/error-codes/DB01001.md) — Connection Failed * [DB01003](/error-codes/DB01003.md) — Transaction Failed --- # DB01003: Transaction Failed ## What This Means[​](#what-this-means "Direct link to What This Means") A database transaction could not be completed. Transactions group multiple operations together — if any part fails, everything is rolled back to maintain data integrity. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Concurrent access** — Multiple operations trying to modify the same data * **Storage full** — No space to write new data * **Database locked** — Another process is locking the database * **Power interruption** — Operation interrupted unexpectedly ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Retry the Operation[​](#1-retry-the-operation "Direct link to 1. Retry the Operation") The issue may be temporary: * Wait a moment * Try the operation again * Avoid rapid repeated attempts ### 2. Check for Conflicts[​](#2-check-for-conflicts "Direct link to 2. Check for Conflicts") If multiple devices or tabs are open: * Use one instance at a time * Close duplicate browser tabs * Coordinate multi-device usage ### 3. Check Storage Space[​](#3-check-storage-space "Direct link to 3. Check Storage Space") Ensure there's space for data: * Check available disk space * Free up space if needed * Clear browser cache (web version) ### 4. Restart the Application[​](#4-restart-the-application "Direct link to 4. Restart the Application") Reset the database state: 1. Close the POS completely 2. Wait a few seconds 3. Reopen the application ### 5. Clear and Re-sync[​](#5-clear-and-re-sync "Direct link to 5. Clear and Re-sync") If transactions consistently fail: 1. Clear local data 2. Login again 3. Sync fresh from server ## Transaction Safety[​](#transaction-safety "Direct link to Transaction Safety") WCPOS uses transactions to ensure: * Data consistency * Complete operations (all or nothing) * Protection against partial updates When a transaction fails, your data remains consistent. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [DB01001](/error-codes/DB01001.md) — Connection Failed * [DB02003](/error-codes/DB02003.md) — Constraint Violation --- # DB02001: Duplicate Record ## What This Means[​](#what-this-means "Direct link to What This Means") The database tried to insert a record with an ID that already exists. Each record must have a unique identifier. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Sync conflict** — Same data synced twice * **Race condition** — Multiple operations creating same record * **Data corruption** — IDs were corrupted or duplicated * **Import issue** — Importing data that already exists ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Refresh Data[​](#1-refresh-data "Direct link to 1. Refresh Data") Re-sync from the server: * Pull latest data * Let the sync process resolve conflicts * The newer data should take precedence ### 2. Retry the Operation[​](#2-retry-the-operation "Direct link to 2. Retry the Operation") If creating new records: * The system may have already created it * Check if the record exists * Avoid clicking submit multiple times ### 3. Clear Local Cache[​](#3-clear-local-cache "Direct link to 3. Clear Local Cache") Reset local data: 1. Clear the local database/cache 2. Login again 3. Sync data fresh ### 4. Check for Duplicates in WooCommerce[​](#4-check-for-duplicates-in-woocommerce "Direct link to 4. Check for Duplicates in WooCommerce") If the issue persists: * Check WooCommerce for duplicate entries * Look for products/orders with same IDs * Clean up any duplicates in the admin ### 5. Report Persistent Issues[​](#5-report-persistent-issues "Direct link to 5. Report Persistent Issues") If this happens frequently: * Note what actions cause it * Check for patterns * Report to support with details ## Why This Matters[​](#why-this-matters "Direct link to Why This Matters") Duplicate IDs would cause: * Confusion about which record is correct * Data overwrites * Sync issues The error prevents data corruption. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [DB02002](/error-codes/DB02002.md) — Record Not Found * [DB02003](/error-codes/DB02003.md) — Constraint Violation --- # DB02002: Record Not Found ## What This Means[​](#what-this-means "Direct link to What This Means") The requested record does not exist in the local database. The POS tried to access a product, customer, order, or other record that isn't stored locally. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Not yet synced** — Data hasn't been downloaded yet * **Deleted on server** — Record was removed in WooCommerce * **Sync not complete** — Initial sync is still running * **Filter applied** — Record excluded by active filters ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Wait for Sync[​](#1-wait-for-sync "Direct link to 1. Wait for Sync") If recently started: * Wait for initial sync to complete * Check sync progress indicator * The record should appear once synced ### 2. Refresh/Re-sync[​](#2-refreshre-sync "Direct link to 2. Refresh/Re-sync") Trigger a data refresh: * Use the refresh/sync button () - short press for sync * **Long press** the sync button for Clear and Refresh option * Pull latest data from server * Wait for completion ### 3. Check WooCommerce[​](#3-check-woocommerce "Direct link to 3. Check WooCommerce") Verify the record exists on the server: * Log into WordPress Admin * Check Products, Orders, or Customers * Confirm the item still exists ### 4. Check Filters[​](#4-check-filters "Direct link to 4. Check Filters") The record might be filtered out: * Review active filters in the POS * Check category filters * Verify visibility settings ### 5. Clear and Re-sync[​](#5-clear-and-re-sync "Direct link to 5. Clear and Re-sync") If sync seems stuck: 1. Clear local data 2. Login again 3. Complete a fresh sync ## Common Scenarios[​](#common-scenarios "Direct link to Common Scenarios") * **Product not showing:** Check if it's published and visible * **Customer not found:** May not have been synced yet * **Order missing:** Could be outside the sync date range ## Related Errors[​](#related-errors "Direct link to Related Errors") * [DB02001](/error-codes/DB02001.md) — Duplicate Record * [API04004](/error-codes/API04004.md) — Missing Response Data --- # DB02003: Constraint Violation ## What This Means[​](#what-this-means "Direct link to What This Means") The data you're trying to save violates database rules. Constraints ensure data integrity by enforcing rules about what data can be stored. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Missing required data** — A required field is empty * **Invalid relationship** — Referencing a record that doesn't exist * **Data type mismatch** — Wrong type of data for the field * **Value out of range** — Number exceeds allowed limits ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check Required Fields[​](#1-check-required-fields "Direct link to 1. Check Required Fields") Ensure all required data is provided: * Customer information (if required) * Product details * Order line items ### 2. Verify References[​](#2-verify-references "Direct link to 2. Verify References") If the error involves relationships: * Ensure referenced products exist * Check that customer IDs are valid * Verify category assignments ### 3. Review Data Values[​](#3-review-data-values "Direct link to 3. Review Data Values") Check for invalid values: * Negative quantities where not allowed * Prices exceeding limits * Invalid status values ### 4. Sync Latest Data[​](#4-sync-latest-data "Direct link to 4. Sync Latest Data") The referenced data may be out of sync: * Refresh data from server * Wait for sync to complete * Retry the operation ### 5. Clear and Retry[​](#5-clear-and-retry "Direct link to 5. Clear and Retry") If data is corrupted: 1. Clear the problematic form 2. Re-enter the data 3. Submit again ## Common Constraint Examples[​](#common-constraint-examples "Direct link to Common Constraint Examples") * **Quantity must be positive** — Can't add 0 or negative items * **Price must be numeric** — Text not allowed in price fields * **Customer must exist** — Can't assign order to non-existent customer ## Related Errors[​](#related-errors "Direct link to Related Errors") * [DB02001](/error-codes/DB02001.md) — Duplicate Record * [DB03003](/error-codes/DB03003.md) — Missing Required Field --- # DB03001: Query Syntax Error ## What This Means[​](#what-this-means "Direct link to What This Means") The database query has syntax errors. This typically indicates a bug in the application rather than a user error. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Software bug** — An issue in the POS application * **Version mismatch** — Incompatible data schema * **Corrupted data** — Data contains unexpected characters * **Encoding issues** — Character encoding problems ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Update the Application[​](#1-update-the-application "Direct link to 1. Update the Application") Ensure you're running the latest version: * Check for POS app updates * Update the WCPOS WordPress plugin * Restart after updating ### 2. Clear Application Data[​](#2-clear-application-data "Direct link to 2. Clear Application Data") Reset to a clean state: * Clear local data/cache * Login again * Re-sync data ### 3. Check for Special Characters[​](#3-check-for-special-characters "Direct link to 3. Check for Special Characters") If the error occurs with specific data: * Check for unusual characters in product names * Look for emojis or special symbols * Try with simpler data ### 4. Report the Bug[​](#4-report-the-bug "Direct link to 4. Report the Bug") If the issue persists: 1. Note what action causes the error 2. Capture any error details 3. Report on [GitHub](https://github.com/wcpos) ## This is Usually a Bug[​](#this-is-usually-a-bug "Direct link to This is Usually a Bug") Query syntax errors are typically bugs in the software, not user errors. If you encounter this: * You're not doing anything wrong * The development team needs to know * A fix will be released in an update ## Workaround[​](#workaround "Direct link to Workaround") Until a fix is available: * Try alternative approaches to accomplish your task * Use WooCommerce admin for affected operations * Check for updates regularly ## Related Errors[​](#related-errors "Direct link to Related Errors") * [DB03002](/error-codes/DB03002.md) — Invalid Data Type * [API03001](/error-codes/API03001.md) — Invalid Request Format --- # DB03002: Invalid Data Type ## What This Means[​](#what-this-means "Direct link to What This Means") The data type doesn't match what the database expects. For example, text was provided where a number was expected. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **User input error** — Entering text in a numeric field * **Import issues** — Imported data has wrong format * **Data corruption** — Values corrupted during transfer * **Plugin conflict** — Another plugin modified data types ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check Your Input[​](#1-check-your-input "Direct link to 1. Check Your Input") Review the data you're entering: * **Prices** — Should be numbers (e.g., `19.99`) * **Quantities** — Should be whole numbers (e.g., `5`) * **IDs** — Should be numeric ### 2. Clear and Re-enter[​](#2-clear-and-re-enter "Direct link to 2. Clear and Re-enter") If data was corrupted: * Clear the field * Enter the value again manually * Avoid copy-pasting from external sources ### 3. Check Source Data[​](#3-check-source-data "Direct link to 3. Check Source Data") If syncing from WooCommerce: * Check the data in WordPress Admin * Look for incorrectly formatted fields * Fix data at the source ### 4. Re-sync Data[​](#4-re-sync-data "Direct link to 4. Re-sync Data") Get fresh data from the server: * Clear local cache * Sync data again * Check if the issue resolves ### 5. Check for Plugin Conflicts[​](#5-check-for-plugin-conflicts "Direct link to 5. Check for Plugin Conflicts") If using other WooCommerce plugins: * They may modify data in unexpected ways * Temporarily disable to test * Report incompatibilities ## Common Examples[​](#common-examples "Direct link to Common Examples") | Field | Expected | Invalid | | ---------- | -------- | ----------------- | | Price | `19.99` | `$19.99` | | Quantity | `5` | `five` | | SKU | `ABC123` | — (any format OK) | | Product ID | `42` | `product-42` | ## Related Errors[​](#related-errors "Direct link to Related Errors") * [DB03003](/error-codes/DB03003.md) — Missing Required Field * [API03003](/error-codes/API03003.md) — Invalid Parameter Value --- # DB03003: Missing Required Field ## What This Means[​](#what-this-means "Direct link to What This Means") A required field was not provided. The database cannot save the record because essential information is missing. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Incomplete form** — Required fields weren't filled in * **Data sync issue** — Required data didn't sync properly * **Validation bypassed** — Form submitted without validation * **Custom field required** — A custom required field is empty ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Complete All Required Fields[​](#1-complete-all-required-fields "Direct link to 1. Complete All Required Fields") Check the form for: * Fields marked with asterisks (\*) * Highlighted or error-marked fields * Empty fields that should have values ### 2. Refresh and Re-enter[​](#2-refresh-and-re-enter "Direct link to 2. Refresh and Re-enter") If the form state is incorrect: 1. Refresh the page/screen 2. Re-enter all information 3. Verify all fields before submitting ### 3. Check WooCommerce Settings[​](#3-check-woocommerce-settings "Direct link to 3. Check WooCommerce Settings") If custom fields are required: 1. Review WooCommerce checkout settings 2. Check for required custom fields 3. Ensure the POS provides these fields ### 4. Sync Required Data[​](#4-sync-required-data "Direct link to 4. Sync Required Data") If related data is missing: * Refresh products/customers/etc. * Wait for sync to complete * Retry the operation ### 5. Review Required Field Settings[​](#5-review-required-field-settings "Direct link to 5. Review Required Field Settings") In WooCommerce Admin: * Check which fields are marked required * Consider if all are truly necessary for POS * Adjust requirements if needed ## Common Required Fields[​](#common-required-fields "Direct link to Common Required Fields") Typically required for orders: * At least one line item * Payment method * Customer (depending on settings) Typically required for products: * Product name * Price (for simple products) ## Related Errors[​](#related-errors "Direct link to Related Errors") * [DB02003](/error-codes/DB02003.md) — Constraint Violation * [API03002](/error-codes/API03002.md) — Missing Required Parameters --- # Payment Errors Payment errors occur during checkout and payment processing. These errors are prefixed with `PY` and relate to issues with payment cards, gateways, and transactions. ## Categories[​](#categories "Direct link to Categories") | Category | Code Range | Description | | -------------------------- | ---------- | ------------------------------------ | | [Card](#card-errors) | PY01xxx | Issues with the payment card | | [Gateway](#gateway-errors) | PY02xxx | Payment gateway communication issues | *** ## Card Errors[​](#card-errors "Direct link to Card Errors") Issues related to the customer's payment card. | Code | Name | Description | | ---------------------------------- | ------------------- | -------------------------------- | | [PY01001](/error-codes/PY01001.md) | Payment Declined | The payment was declined | | [PY01002](/error-codes/PY01002.md) | Insufficient Funds | Not enough funds for the payment | | [PY01003](/error-codes/PY01003.md) | Card Expired | The payment card has expired | | [PY01004](/error-codes/PY01004.md) | Invalid Card Number | The card number is not valid | ## Gateway Errors[​](#gateway-errors "Direct link to Gateway Errors") Issues communicating with the payment gateway. | Code | Name | Description | | ---------------------------------- | --------------------- | ---------------------------------------- | | [PY02001](/error-codes/PY02001.md) | Payment Gateway Error | Error communicating with payment gateway | | [PY02002](/error-codes/PY02002.md) | Payment Timeout | Payment processing timed out | --- # PY01001: Payment Declined ## What This Means[​](#what-this-means "Direct link to What This Means") The payment was declined by the payment processor or card issuer. The transaction could not be completed. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Insufficient funds** — Not enough money in the account * **Card limit exceeded** — Transaction exceeds card limits * **Fraud protection** — Bank flagged as suspicious * **Incorrect card details** — Card number, CVV, or expiry wrong * **Card restrictions** — Card not enabled for this type of purchase ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Verify Card Details[​](#1-verify-card-details "Direct link to 1. Verify Card Details") Check that the entered information is correct: * Card number (all digits) * Expiration date * CVV/security code * Billing address (if required) ### 2. Try Again[​](#2-try-again "Direct link to 2. Try Again") Sometimes temporary issues occur: * Wait a moment * Re-enter the card details * Try the transaction again ### 3. Use a Different Payment Method[​](#3-use-a-different-payment-method "Direct link to 3. Use a Different Payment Method") If the card continues to decline: * Try a different card * Use cash payment * Use an alternative payment method ### 4. Contact the Bank[​](#4-contact-the-bank "Direct link to 4. Contact the Bank") The cardholder may need to: * Verify the transaction with their bank * Lift any fraud blocks * Confirm the card is active * Check for spending limits ### 5. Check for Restrictions[​](#5-check-for-restrictions "Direct link to 5. Check for Restrictions") Some cards have restrictions: * International transactions disabled * Online/POS transactions blocked * Certain merchant categories blocked ## For Store Owners[​](#for-store-owners "Direct link to For Store Owners") If you're seeing frequent declines: * Verify your merchant account is in good standing * Check payment gateway configuration * Review fraud prevention settings * Consider contacting your payment processor ## Related Errors[​](#related-errors "Direct link to Related Errors") * [PY01002](/error-codes/PY01002.md) — Insufficient Funds * [PY02001](/error-codes/PY02001.md) — Payment Gateway Error --- # PY01002: Insufficient Funds ## What This Means[​](#what-this-means "Direct link to What This Means") The payment was declined because there isn't enough money in the account to cover the transaction. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Low account balance** — Not enough funds available * **Pending transactions** — Other pending transactions reducing available balance * **Credit limit reached** — For credit cards, the limit is maxed out * **Hold on funds** — Funds are on hold for other transactions ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Use a Different Payment Method[​](#1-use-a-different-payment-method "Direct link to 1. Use a Different Payment Method") The quickest solution: * Try a different card * Use cash * Split payment across multiple methods (if supported) ### 2. Reduce the Order Amount[​](#2-reduce-the-order-amount "Direct link to 2. Reduce the Order Amount") If partial payment is possible: * Remove some items * Apply discounts or coupons * Complete a smaller transaction ### 3. Customer Actions[​](#3-customer-actions "Direct link to 3. Customer Actions") The customer may need to: * Transfer funds to the account * Wait for pending transactions to clear * Pay off credit card balance * Request a credit limit increase ### 4. Split the Transaction[​](#4-split-the-transaction "Direct link to 4. Split the Transaction") If your POS supports split payments: * Pay part with one card * Pay the remainder with another method ## Privacy Note[​](#privacy-note "Direct link to Privacy Note") When communicating this to customers: * Be discreet about the specific decline reason * Simply state "the card was declined" * Allow them to try another payment method privately ## Related Errors[​](#related-errors "Direct link to Related Errors") * [PY01001](/error-codes/PY01001.md) — Payment Declined * [PY01003](/error-codes/PY01003.md) — Card Expired --- # PY01003: Card Expired ## What This Means[​](#what-this-means "Direct link to What This Means") The payment card has passed its expiration date and can no longer be used for transactions. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Expired card** — The card's valid-through date has passed * **Incorrect expiry entered** — Expiration date was entered wrong * **New card not activated** — Replacement card received but not yet activated ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check the Expiration Date[​](#1-check-the-expiration-date "Direct link to 1. Check the Expiration Date") Look at the card: * Find the expiration date (MM/YY format) * Compare with current date * Verify the entered date matches the card ### 2. Use a Different Card[​](#2-use-a-different-card "Direct link to 2. Use a Different Card") If the card is truly expired: * Use a different, valid card * Use cash or alternative payment * Ask if customer has a replacement card ### 3. Get the Updated Card[​](#3-get-the-updated-card "Direct link to 3. Get the Updated Card") The cardholder should: * Check mail for a replacement card * Activate the new card if received * Contact their bank if no replacement arrived ### 4. Verify Entry[​](#4-verify-entry "Direct link to 4. Verify Entry") Double-check the expiration entry: * MM/YY format * Correct month and year * No typos ## Customer Service Tips[​](#customer-service-tips "Direct link to Customer Service Tips") When a card is expired: * Politely inform the customer * Suggest they check for a replacement card * Offer alternative payment options * Be understanding — this happens to everyone ## Related Errors[​](#related-errors "Direct link to Related Errors") * [PY01001](/error-codes/PY01001.md) — Payment Declined * [PY01004](/error-codes/PY01004.md) — Invalid Card Number --- # PY01004: Invalid Card Number ## What This Means[​](#what-this-means "Direct link to What This Means") The card number entered is not valid. Card numbers follow specific patterns and include check digits for validation. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Typo** — One or more digits entered incorrectly * **Missing digits** — Not all digits were entered * **Extra digits** — Too many digits entered * **Wrong card** — Different card number than physical card * **Card reader error** — Chip/swipe read the wrong data ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Re-enter the Card Number[​](#1-re-enter-the-card-number "Direct link to 1. Re-enter the Card Number") Carefully enter all digits: * Check the physical card * Enter each digit slowly * Verify the full number before submitting ### 2. Check Card Type[​](#2-check-card-type "Direct link to 2. Check Card Type") Ensure the card type is supported: * Visa (starts with 4) * Mastercard (starts with 51-55 or 22-27) * Amex (starts with 34 or 37) * Discover (starts with 6011, 622, 644-649, 65) ### 3. Try Again with Card Reader[​](#3-try-again-with-card-reader "Direct link to 3. Try Again with Card Reader") If using a chip/swipe reader: * Clean the card chip * Try a different read method (chip vs swipe) * Manually enter if reader fails ### 4. Use a Different Card[​](#4-use-a-different-card "Direct link to 4. Use a Different Card") If the card number continues to fail: * The card may be damaged * Try a different card * Use an alternative payment method ### 5. Check for Card Damage[​](#5-check-for-card-damage "Direct link to 5. Check for Card Damage") Physical card issues: * Scratched magnetic stripe * Damaged chip * Worn or faded numbers * Card may need replacement ## Card Number Formats[​](#card-number-formats "Direct link to Card Number Formats") | Card Type | Length | Starts With | | ---------- | ------ | ---------------------- | | Visa | 16 | 4 | | Mastercard | 16 | 51-55, 22-27 | | Amex | 15 | 34, 37 | | Discover | 16 | 6011, 622, 644-649, 65 | ## Related Errors[​](#related-errors "Direct link to Related Errors") * [PY01001](/error-codes/PY01001.md) — Payment Declined * [PY01003](/error-codes/PY01003.md) — Card Expired --- # PY02001: Payment Gateway Error ## What This Means[​](#what-this-means "Direct link to What This Means") An error occurred while communicating with the payment gateway. The payment processor couldn't complete the request. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Gateway downtime** — The payment service is experiencing issues * **Configuration error** — Gateway settings are incorrect * **API credentials** — Invalid or expired API keys * **Network issues** — Connection problems to the gateway ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Retry the Transaction[​](#1-retry-the-transaction "Direct link to 1. Retry the Transaction") Sometimes gateways have temporary issues: * Wait a moment * Try processing the payment again * The issue may resolve itself ### 2. Check Gateway Status[​](#2-check-gateway-status "Direct link to 2. Check Gateway Status") Visit your payment provider's status page: * Stripe: status.stripe.com * PayPal: Check PayPal community or status * Square: status.squareup.com * Check for known outages ### 3. Verify Gateway Configuration[​](#3-verify-gateway-configuration "Direct link to 3. Verify Gateway Configuration") In WooCommerce Admin: 1. Go to WooCommerce → Settings → Payments 2. Click on your payment gateway 3. Verify API keys are correct 4. Check that test/live mode matches your keys ### 4. Check API Credentials[​](#4-check-api-credentials "Direct link to 4. Check API Credentials") Ensure credentials are valid: * API keys haven't expired * Using live keys for live transactions * Using test keys for test transactions * Credentials match the correct account ### 5. Test with a Different Gateway[​](#5-test-with-a-different-gateway "Direct link to 5. Test with a Different Gateway") If available: * Try processing with an alternative gateway * Use cash payment as a fallback * Complete the sale and reconcile later ## For Store Owners[​](#for-store-owners "Direct link to For Store Owners") Common configuration issues: * Mixing test and live API keys * API keys from different accounts * Disabled payment methods * Expired or revoked credentials Contact your payment provider's support if the issue persists. ## Related Errors[​](#related-errors "Direct link to Related Errors") * [PY02002](/error-codes/PY02002.md) — Payment Timeout * [PY01001](/error-codes/PY01001.md) — Payment Declined --- # PY02002: Payment Timeout ## What This Means[​](#what-this-means "Direct link to What This Means") The payment processing took too long and timed out. The payment gateway didn't respond within the expected time. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Gateway overload** — Payment processor is experiencing high volume * **Network latency** — Slow connection to the payment service * **Processing delay** — Complex fraud checks or verification * **Server issues** — Payment gateway having performance issues ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Check if Payment Succeeded[​](#1-check-if-payment-succeeded "Direct link to 1. Check if Payment Succeeded") **Important:** Before retrying, verify the payment status: * Check your payment gateway dashboard * Look for the transaction in WooCommerce * Don't process again if it actually succeeded ### 2. Retry with Caution[​](#2-retry-with-caution "Direct link to 2. Retry with Caution") If the payment definitely didn't go through: * Wait 30-60 seconds * Try again * Watch for duplicate charges ### 3. Check Your Connection[​](#3-check-your-connection "Direct link to 3. Check Your Connection") Ensure stable connectivity: * Test your internet connection * Try a wired connection if on WiFi * Check for network issues ### 4. Try at a Less Busy Time[​](#4-try-at-a-less-busy-time "Direct link to 4. Try at a Less Busy Time") If the gateway is overloaded: * Retail peak times may cause slowdowns * Try again shortly * Use an alternative payment method ### 5. Contact Payment Provider[​](#5-contact-payment-provider "Direct link to 5. Contact Payment Provider") If timeouts persist: * Check their status page * Contact their support * Report ongoing issues ## Avoiding Duplicate Charges[​](#avoiding-duplicate-charges "Direct link to Avoiding Duplicate Charges") When a timeout occurs: 1. **Don't immediately retry** — Check the status first 2. **Review transactions** — Check both gateway and WooCommerce 3. **Refund duplicates** — Process refunds for any accidental duplicates 4. **Inform the customer** — Explain the situation if there's a delay ## Alternative Actions[​](#alternative-actions "Direct link to Alternative Actions") If payment keeps timing out: * Accept cash payment * Record as "pay later" if allowed * Use a different payment method ## Related Errors[​](#related-errors "Direct link to Related Errors") * [PY02001](/error-codes/PY02001.md) — Payment Gateway Error * [API01001](/error-codes/API01001.md) — Connection Timeout --- # System Errors System errors are related to device resources and system configuration. These errors are prefixed with `SY` and indicate issues with your device or the POS application itself. ## Categories[​](#categories "Direct link to Categories") | Category | Code Range | Description | | ---------------------------- | ---------- | -------------------------------------- | | [Resource](#resource-errors) | SY01xxx | Memory, disk, and permission issues | | [Service](#service-errors) | SY02xxx | Configuration and service availability | *** ## Resource Errors[​](#resource-errors "Direct link to Resource Errors") Issues with device resources like memory, storage, and permissions. | Code | Name | Description | | ---------------------------------- | ----------------- | ------------------------------- | | [SY01001](/error-codes/SY01001.md) | Out of Memory | Device is running low on memory | | [SY01002](/error-codes/SY01002.md) | Disk Full | Device storage is full | | [SY01003](/error-codes/SY01003.md) | Permission Denied | System permission was denied | ## Service Errors[​](#service-errors "Direct link to Service Errors") Issues with system configuration and service availability. | Code | Name | Description | | ---------------------------------- | --------------------- | ----------------------------------- | | [SY02001](/error-codes/SY02001.md) | Invalid Configuration | System configuration is invalid | | [SY02002](/error-codes/SY02002.md) | Service Unavailable | A required service is not available | --- # SY01001: Out of Memory ## What This Means[​](#what-this-means "Direct link to What This Means") Your device is running low on memory (RAM) and cannot complete the requested operation. The POS needs sufficient memory to function properly. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Too many apps open** — Other applications using memory * **Large data set** — Many products/customers loaded * **Memory leak** — Application not releasing memory properly * **Insufficient RAM** — Device doesn't have enough memory ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Close Other Applications[​](#1-close-other-applications "Direct link to 1. Close Other Applications") Free up memory: * Close unused browser tabs * Close other applications * Close background programs ### 2. Restart the POS[​](#2-restart-the-pos "Direct link to 2. Restart the POS") Refresh the application memory: 1. Close the POS completely 2. Wait a few seconds 3. Reopen the application ### 3. Restart Your Device[​](#3-restart-your-device "Direct link to 3. Restart Your Device") A full restart clears all memory: 1. Save any open work 2. Restart your computer/device 3. Open only the POS when starting again ### 4. Clear Browser Data (Web Version)[​](#4-clear-browser-data-web-version "Direct link to 4. Clear Browser Data (Web Version)") If using in a browser: * Clear browser cache * Close and reopen the browser * Use fewer browser tabs ### 5. Reduce Data Load[​](#5-reduce-data-load "Direct link to 5. Reduce Data Load") If you have a very large catalogue: * Use filters to load less data at once * Consider paginating results * Limit the sync scope if possible ## Minimum Requirements[​](#minimum-requirements "Direct link to Minimum Requirements") Ensure your device meets minimum specs: * **RAM:** 4GB minimum, 8GB recommended * **Browser:** Modern browser (Chrome, Firefox, Edge) * **Desktop App:** Check release notes for requirements ## Ongoing Issues[​](#ongoing-issues "Direct link to Ongoing Issues") If you frequently run out of memory: * Consider upgrading your device's RAM * Use a device with more resources * Report the issue if it seems excessive ## Related Errors[​](#related-errors "Direct link to Related Errors") * [SY01002](/error-codes/SY01002.md) — Disk Full * [DB01001](/error-codes/DB01001.md) — Connection Failed --- # SY01002: Disk Full ## What This Means[​](#what-this-means "Direct link to What This Means") Your device's storage is full. The POS cannot save data or continue operating without available disk space. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Storage full** — No free space on the drive * **Large local database** — POS data using significant space * **Temp files** — Temporary files consuming space * **Other applications** — Other apps filling the disk ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Free Up Disk Space[​](#1-free-up-disk-space "Direct link to 1. Free Up Disk Space") Delete unnecessary files: * Empty the trash/recycle bin * Remove old downloads * Delete unused applications * Clear temporary files ### 2. Check Available Space[​](#2-check-available-space "Direct link to 2. Check Available Space") **Windows:** * Open File Explorer * Right-click the drive → Properties * View used and free space **macOS:** * Apple menu → About This Mac * Click Storage ### 3. Clear Browser Data (Web Version)[​](#3-clear-browser-data-web-version "Direct link to 3. Clear Browser Data (Web Version)") Browsers store data locally: * Clear cache and cookies * Remove old site data * Check browser storage usage ### 4. Move or Delete Large Files[​](#4-move-or-delete-large-files "Direct link to 4. Move or Delete Large Files") Find and handle large files: * Old videos or photos * Large downloads * Unused software * Backup files that can be moved to external storage ### 5. Check POS Data[​](#5-check-pos-data "Direct link to 5. Check POS Data") If POS data is very large: * The local database may need cleaning * Consider clearing and re-syncing * Check if old data can be purged ## Recommended Free Space[​](#recommended-free-space "Direct link to Recommended Free Space") Keep at least: * **10GB** free for normal operation * **20GB+** for large catalogs * More space is always better ## Preventing Future Issues[​](#preventing-future-issues "Direct link to Preventing Future Issues") * Regularly clean up unnecessary files * Set up automatic temp file cleanup * Monitor disk space usage * Consider larger storage if frequently full ## Related Errors[​](#related-errors "Direct link to Related Errors") * [SY01001](/error-codes/SY01001.md) — Out of Memory * [DB01001](/error-codes/DB01001.md) — Connection Failed --- # SY01003: Permission Denied ## What This Means[​](#what-this-means "Direct link to What This Means") The POS application doesn't have permission to access a required resource. This could be a file, folder, or system feature. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **File permissions** — Can't read or write to needed files * **App permissions** — Application lacks required permissions * **Protected folder** — Trying to access a restricted location * **Security software** — Antivirus blocking access ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Run as Administrator (Windows)[​](#1-run-as-administrator-windows "Direct link to 1. Run as Administrator (Windows)") Right-click the app and select "Run as administrator" if needed for initial setup. ### 2. Check Application Permissions[​](#2-check-application-permissions "Direct link to 2. Check Application Permissions") **macOS:** * System Preferences → Security & Privacy → Privacy * Check that the app has necessary permissions **Windows:** * Settings → Privacy * Review app permissions ### 3. Check Folder Permissions[​](#3-check-folder-permissions "Direct link to 3. Check Folder Permissions") Ensure the app can access its data folder: * The user should own the app data directory * Write permissions should be enabled * No read-only flags on the folder ### 4. Review Antivirus Settings[​](#4-review-antivirus-settings "Direct link to 4. Review Antivirus Settings") Security software may block access: * Check antivirus logs for blocks * Add the POS app to the allowlist * Whitelist the app data folder ### 5. Reinstall the Application[​](#5-reinstall-the-application "Direct link to 5. Reinstall the Application") If permissions are corrupted: 1. Uninstall the POS application 2. Restart your device 3. Reinstall to a standard location 4. Run with normal (non-admin) permissions ## Browser Permissions (Web Version)[​](#browser-permissions-web-version "Direct link to Browser Permissions (Web Version)") If using the web version: * Allow local storage for the site * Enable cookies for the site * Don't use overly restrictive browser settings ## Related Errors[​](#related-errors "Direct link to Related Errors") * [SY01001](/error-codes/SY01001.md) — Out of Memory * [DB01001](/error-codes/DB01001.md) — Connection Failed --- # SY02001: Invalid Configuration ## What This Means[​](#what-this-means "Direct link to What This Means") The system configuration is invalid or corrupted. The POS application found configuration settings that don't make sense or are incomplete. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Corrupted settings** — Configuration file became corrupted * **Incomplete setup** — Setup process wasn't completed * **Manual editing error** — Config files were incorrectly modified * **Version upgrade issue** — Old config incompatible with new version ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Reset to Default Settings[​](#1-reset-to-default-settings "Direct link to 1. Reset to Default Settings") If available in the app: * Look for "Reset Settings" or "Restore Defaults" * This clears custom settings but fixes corruption ### 2. Complete the Setup[​](#2-complete-the-setup "Direct link to 2. Complete the Setup") If setup wasn't finished: 1. Start the setup process again 2. Complete all required steps 3. Verify configuration before finishing ### 3. Clear Application Data[​](#3-clear-application-data "Direct link to 3. Clear Application Data") Remove corrupted config: * **Desktop:** Delete app data folder, restart app * **Browser:** Clear site data, reload ### 4. Reinstall the Application[​](#4-reinstall-the-application "Direct link to 4. Reinstall the Application") For persistent issues: 1. Uninstall completely 2. Remove any leftover data folders 3. Reinstall fresh 4. Complete setup from scratch ### 5. Check for Updates[​](#5-check-for-updates "Direct link to 5. Check for Updates") Configuration formats may change: * Update the POS application * Update the WCPOS plugin * Reconfigure after update ## What Gets Reset[​](#what-gets-reset "Direct link to What Gets Reset") When resetting configuration: * You'll need to log in again * Custom settings will be lost * Data will need to re-sync * But your WooCommerce data is safe on the server ## Related Errors[​](#related-errors "Direct link to Related Errors") * [SY02002](/error-codes/SY02002.md) — Service Unavailable * [API06003](/error-codes/API06003.md) — Invalid Site Configuration --- # SY02002: Service Unavailable ## What This Means[​](#what-this-means "Direct link to What This Means") A required service or component is not available. The POS depends on various services to function, and one of them is currently inaccessible. ## Common Causes[​](#common-causes "Direct link to Common Causes") * **Background service stopped** — A required service isn't running * **System resource issue** — Not enough resources to start the service * **Dependency failure** — A service this depends on failed * **Startup issue** — Service failed to start properly * **Server error** — The WooCommerce server returned a 5xx error ## Server Error Mapping[​](#server-error-mapping "Direct link to Server Error Mapping") This error code is triggered when the server returns: | Server Code | Source | | ----------- | ---------------------------------------------------- | | HTTP 5xx | Any server error response (500, 502, 503, 504, etc.) | ## How to Fix[​](#how-to-fix "Direct link to How to Fix") ### 1. Restart the Application[​](#1-restart-the-application "Direct link to 1. Restart the Application") Close and reopen the POS: 1. Fully close the application 2. Wait a few seconds 3. Start it again ### 2. Restart Your Device[​](#2-restart-your-device "Direct link to 2. Restart Your Device") A full restart often resolves service issues: 1. Save any important work 2. Restart your computer 3. Try the POS again ### 3. Check System Resources[​](#3-check-system-resources "Direct link to 3. Check System Resources") Ensure system resources are available: * Close unnecessary applications * Check memory usage * Check disk space ### 4. Update the Application[​](#4-update-the-application "Direct link to 4. Update the Application") Ensure you're on the latest version: * Check for available updates * Install any pending updates * Restart after updating ### 5. Reinstall if Necessary[​](#5-reinstall-if-necessary "Direct link to 5. Reinstall if Necessary") If the service remains unavailable: 1. Uninstall the application 2. Restart your device 3. Download the latest version 4. Install fresh ## Browser-Specific (Web Version)[​](#browser-specific-web-version "Direct link to Browser-Specific (Web Version)") For the web version: * Ensure JavaScript is enabled * Check that required browser features aren't blocked * Try a different browser * Disable browser extensions that might interfere ## When to Contact Support[​](#when-to-contact-support "Direct link to When to Contact Support") If this error persists: * Note when it occurs * Check if specific actions trigger it * Report with details for investigation ## Related Errors[​](#related-errors "Direct link to Related Errors") * [SY02001](/error-codes/SY02001.md) — Invalid Configuration * [API01008](/error-codes/API01008.md) — Website Unavailable --- # Extensions WCPOS supports extensions that add new functionality to your point of sale. The extension directory lets you browse available extensions, install them directly from the POS settings, and manage updates. Pro Feature Installing and managing extensions requires [WCPOS Pro](/getting-started/pro-license.md). The free version displays the extension catalog but disables install and activation controls. ## Available Extensions[​](#available-extensions "Direct link to Available Extensions") ### Payment Gateways[​](#payment-gateways "Direct link to Payment Gateways") Custom checkout gateways designed for in-person POS use. [Stripe TerminalIn-person card payments on Stripe Terminal hardware (S700, WisePOS E). Supports MOTO and simulator mode.](/payment/gateways/stripe-terminal.md) [SumUp TerminalAccept card payments through SumUp card readers.](/payment/gateways/sumup-terminal.md) [Vipps MobilePayPhone-based payments via QR code or push notification. Vipps (Norway), MobilePay (Denmark, Finland).](/payment/gateways/vipps-mobilepay.md) [Email InvoiceEmail the customer a payment link to settle the order online.](/payment/gateways/email-invoice.md) Want to build your own? Start from the [Gateway Template](/reference/gateway-template.md) — or see the [Custom Gateways overview](/payment/gateways/.md) for the full list. ### Multilingual[​](#multilingual "Direct link to Multilingual") Filter POS products by language so translated duplicates don't appear in cashier search and the catalog grid. [WCPOS PolylangPolylang integration — language-aware product sync and per-store language selection for WCPOS Pro.](/extensions/polylang.md) [WCPOS WPMLWPML integration — filter POS products to a single language.](/extensions/wpml.md) [WCPOS WP MultilangWP Multilang integration — filter POS products to a single language.](/extensions/wp-multilang.md) ### Coupons and Store Credit[​](#coupons-and-store-credit "Direct link to Coupons and Store Credit") [WCPOS StoreApps Smart CouponsRedeem StoreApps Smart Coupons store credit in WCPOS, with receipt balance labels and order-note audit history.](/extensions/storeapps-smart-coupons.md) ### Inventory[​](#inventory "Direct link to Inventory") [WCPOS ATUM IntegrationLink WCPOS Pro stores to ATUM Multi-Inventory locations for per-location stock, pricing, and SKUs.](/extensions/atum.md) ## Browsing Extensions[​](#browsing-extensions "Direct link to Browsing Extensions") Open the extension directory from `POS Settings > Extensions` (also labeled **Plugins** in some versions). The directory displays a card grid of available extensions. Each card shows: * **Icon** (or a puzzle-piece fallback if the extension doesn't provide one) * **Name and version** * **Description** * **Category badge** * **Status** — active, inactive, update available, or not installed ### Filtering and Search[​](#filtering-and-search "Direct link to Filtering and Search") Use the **category pill buttons** at the top to filter extensions by category. You can also use the **search field** to find extensions by name, description, or tags. ## Installing an Extension[​](#installing-an-extension "Direct link to Installing an Extension") 1. Open `POS Settings > Extensions`. 2. Find the extension you want and click **Install**. 3. The extension is downloaded and installed using the WordPress plugin installer. 4. Once installed, click **Activate** to enable it. Behind the scenes, WCPOS uses WordPress's native `Plugin_Upgrader` to handle installation, so extensions follow the same process as any WordPress plugin. ## Activating and Deactivating[​](#activating-and-deactivating "Direct link to Activating and Deactivating") Each installed extension has **Activate** and **Deactivate** buttons on its card. * **Activate** enables the extension so it can run in the POS. * **Deactivate** disables it without uninstalling. The extension files remain on your server and can be reactivated at any time. ## Updating Extensions[​](#updating-extensions "Direct link to Updating Extensions") When a newer version of an installed extension is available, the card shows an **Update Available** badge and an **Update** button. ### Auto-Updates[​](#auto-updates "Direct link to Auto-Updates") Extensions installed from the directory have **auto-update enabled by default**. You can toggle auto-updates on or off per extension from its card in the directory. When auto-update is on, WordPress will apply new versions automatically, just like it does for plugins with auto-update enabled. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### "Requires Pro" Message on Buttons[​](#requires-pro-message-on-buttons "Direct link to \"Requires Pro\" Message on Buttons") The install, activate, and update buttons are disabled in the free version of WCPOS. Upgrade to [WCPOS Pro](/getting-started/pro-license.md) to manage extensions. ### Extension Fails to Install[​](#extension-fails-to-install "Direct link to Extension Fails to Install") * Check that your WordPress server has write permissions to the `wp-content/plugins` directory. * Verify that your server can make outbound HTTPS requests (some hosts block external downloads). * Look at the error details in `WP Admin > POS > Support > Logs`. ### Extension Not Appearing After Install[​](#extension-not-appearing-after-install "Direct link to Extension Not Appearing After Install") * Refresh the POS — the extension list is cached for up to 12 hours. * Confirm the extension is activated (installed but inactive extensions won't run). ### Catalog Not Loading[​](#catalog-not-loading "Direct link to Catalog Not Loading") The extension catalog is fetched from a remote source and cached locally for 12 hours. If the catalog doesn't load: * Check your server's internet connectivity. * Try again after the cache expires, or clear your server's transient cache. *** ## For Developers[​](#for-developers "Direct link to For Developers") ### Creating a POS Extension[​](#creating-a-pos-extension "Direct link to Creating a POS Extension") A WCPOS extension is a standard WordPress plugin that integrates with the POS through WCPOS hooks and APIs. To create one: 1. **Start with a WordPress plugin.** Your extension needs a standard plugin header and entry file, just like any WooCommerce or WordPress plugin. 2. **Integrate with WCPOS.** Use the hooks and filters provided by WCPOS to add functionality to the POS interface or backend. 3. **Host releases on GitHub.** The extension directory uses GitHub Releases to track versions and deliver updates. ### Submitting to the Directory[​](#submitting-to-the-directory "Direct link to Submitting to the Directory") The extension catalog is maintained in the [`wcpos/extensions`](https://github.com/wcpos/extensions) GitHub repository. To list your extension: 1. Review the catalog format and metadata requirements in the repository's README. 2. Open a pull request to add your extension's metadata to `catalog.json`. 3. Once merged, your extension will appear in the directory for all WCPOS Pro users. ### GitHub Release Conventions[​](#github-release-conventions "Direct link to GitHub Release Conventions") The update lifecycle relies on GitHub Releases: * **Tag versions** using semantic versioning (e.g., `v1.0.0`, `v1.2.3`). * **Attach the plugin zip** as a release asset — this is the file that gets downloaded when a user installs or updates. * **Publish the release** (not draft) so the directory can detect it. When you publish a new release, users with your extension installed will see the update available in their extension directory. If auto-update is enabled, it will be applied automatically. For full details on the catalog schema and submission process, see the [`wcpos/extensions`](https://github.com/wcpos/extensions) repository. --- # WCPOS ATUM Integration Integrates [ATUM Multi-Inventory](https://www.stockmanagementlabs.com/addons/atum-multi-inventory/) with [WCPOS Pro](/getting-started/pro-license.md), enabling location-based inventory, pricing, and SKUs at the Point of Sale. ATUM Multi-Inventory lets you split a product's stock across multiple inventory locations — warehouses, retail stores, and so on. This plugin connects those ATUM locations to WCPOS Pro [stores](/stores/.md) so each POS terminal sees the correct stock levels, prices, and SKUs for its physical location. ## Features[​](#features "Direct link to Features") #### Per-Location Stock Each store pulls stock quantities from its assigned ATUM inventory location rather than aggregate WooCommerce stock. #### Flexible Pricing Choose pricing from WooCommerce defaults, WCPOS Pro per-store prices, or ATUM location-specific prices. #### Location SKUs Optionally swap the product's main SKU for an ATUM location-specific SKU at the POS. #### Audit-Safe Stock Movement Orders deduct and restore stock at the correct ATUM location, with full audit trail in `atum_inventory_orders`. #### Product Edit Write-Back POS edits to stock, price, and SKU sync back to the mapped ATUM inventory row for that location. ## Installation[​](#installation "Direct link to Installation") 1 #### Install ATUM and Multi-Inventory Install [ATUM Inventory Management](https://wordpress.org/plugins/atum-stock-manager-for-woocommerce/) and the [ATUM Multi-Inventory add-on](https://www.stockmanagementlabs.com/addons/atum-multi-inventory/). Configure your inventory locations in ATUM. 2 #### Install WCPOS ATUM Integration Install from `WP Admin > POS > Settings > Extensions`, or download the latest release from the [GitHub releases page](https://github.com/wcpos/wcpos-atum/releases) and upload via `Plugins > Add New > Upload Plugin`. 3 #### Map stores to ATUM locations Go to `POS > Stores`, edit a store, and configure the **ATUM Inventory** sidebar section. Pick the inventory location the store should use, choose a pricing source, and optionally enable SKU overrides. ## Store Configuration[​](#store-configuration "Direct link to Store Configuration") The plugin adds an **ATUM Inventory** section to the WCPOS Pro store editor sidebar with three settings per store: * **Inventory Location** — which ATUM location this store pulls stock from. * **Pricing Source** — where product prices come from: * *Default* — standard WooCommerce prices * *WCPOS Pro* — per-store pricing set in WCPOS Pro * *ATUM* — location-specific prices from the ATUM inventory * **SKU Override** — optionally use location-specific SKUs from ATUM instead of the product's main SKU. ## POS Behavior[​](#pos-behavior "Direct link to POS Behavior") When a store has an ATUM location assigned, the product data served to the POS is automatically adjusted: * **Stock quantities** reflect the specific location's inventory, not the aggregate WooCommerce stock. * **Stock status** is recalculated based on the location's quantity. * **Prices** come from the configured pricing source. * **SKUs** are swapped to the ATUM location SKU if override is enabled. All adjustments happen transparently through the WCPOS REST API — no changes are needed on the POS app side. Product edits made from the POS are also written back to the mapped ATUM inventory row; see [Product Edit Write-Back](#product-edit-write-back) below. ## Stock Management[​](#stock-management "Direct link to Stock Management") For POS orders placed at stores with a mapped ATUM location, the plugin lets ATUM's native stock deduction flow handle the write — but steers it to the correct location: 1. **REST payload injection.** When the POS creates or updates an order, the plugin injects a `mi_inventories` entry onto each line item so ATUM knows which location to draw from. Without this, ATUM would fall back to the main inventory. 2. **Location-scoped inventory filter.** The plugin filters ATUM's candidate inventory list to only those linked to the store's mapped location term, ensuring the right one is picked on both reduction and restoration. ATUM itself performs the actual stock change on order and refund, writing rows to `atum_inventory_orders` with the real `order_id` — preserving ATUM's audit trail. ## Product Edit Write-Back[​](#product-edit-write-back "Direct link to Product Edit Write-Back") When a cashier or manager edits a product or variation from the POS, the changes sync back to the mapped ATUM inventory row for that store's location — not just the main WooCommerce product. This keeps each location's stock, price, and SKU in sync with ATUM without manual updates in `WP Admin`. The write-back is triggered on WCPOS product and variation REST updates (`POST`, `PUT`, `PATCH` to `/wcpos/v1/products/...`) that include a `store_id`. The plugin looks up the store's mapped ATUM location and updates only the inventory row for that location — other locations are untouched. ### What Syncs[​](#what-syncs "Direct link to What Syncs") The write-back respects each store's configuration so ATUM data only changes when the store actually owns that data: | Field | When it syncs | | -------------------------------------- | -------------------------------------------------------------------------------- | | **Stock quantity** | Always — every store with a mapped ATUM location keeps its location row in sync. | | **Regular price / Sale price / Price** | Only when the store's **Pricing Source** is set to *ATUM*. | | **SKU** | Only when **SKU Override** is enabled for the store. | If the store uses *Default* or *WCPOS Pro* pricing, ATUM price fields are left alone so ATUM continues to serve as a reference price rather than the source of truth. The same applies to SKUs when override is off. ### What Doesn't Trigger Write-Back[​](#what-doesnt-trigger-write-back "Direct link to What Doesn't Trigger Write-Back") * Product creation (only updates write back — new products fall through to WooCommerce's normal save path). * Requests without a `store_id` — the POS has to tell the plugin which location to write to. * Stores without a mapped ATUM location. * Products without an existing ATUM inventory row for the store's location — the plugin will not create new inventory rows, only update existing ones. ## Requirements[​](#requirements "Direct link to Requirements") WordPress : WordPress 5.9+ with PHP 7.4+ WooCommerce : WooCommerce installed and activated ATUM : ATUM Inventory Management and ATUM Multi-Inventory add-on WCPOS : WCPOS Pro — multi-store is a Pro feature ## Related[​](#related "Direct link to Related") * [Multi-Store](/stores/.md) — per-store pricing, addresses, and cashier assignment * Source: [github.com/wcpos/wcpos-atum](https://github.com/wcpos/wcpos-atum) --- # WCPOS Polylang Adds [Polylang](https://polylang.pro/) awareness to WCPOS so the POS only shows products for a single language — no duplicated translations in product search, the catalog grid, or cashier workflows. WCPOS Pro stores can pin a per-store language; free installs fall back to the Polylang default language. ## What It Does[​](#what-it-does "Direct link to What It Does") * Filters WCPOS product and variation REST queries by language. * Intercepts WCPOS **fast-sync** routes (the lightweight `posts_per_page=-1` + `fields` requests the POS uses to refresh its local index) so translated duplicates never reach the client. * On free installs, applies the Polylang default language. * On Pro installs, each store can choose its own language from a new **Language** section in the store editor. * Respects WCPOS **POS-only** product visibility when building the fast-sync payload. The integration no-ops cleanly when Polylang is not active — you can install the plugin ahead of enabling Polylang without errors. ## Installation[​](#installation "Direct link to Installation") 1 #### Install Polylang Install [Polylang](https://wordpress.org/plugins/polylang/) (or Polylang Pro) and configure your site languages as normal. Make sure at least one language is set as the default. 2 #### Install WCPOS Polylang Install from the WCPOS extensions directory at `WP Admin > POS > Settings > Extensions`, or download the latest release from the [GitHub releases page](https://github.com/wcpos/wcpos-polylang/releases) and upload via `Plugins > Add New > Upload Plugin`. 3 #### (Pro) Set a per-store language If you run [multiple stores](/stores/.md) on WCPOS Pro, go to `POS > Stores`, edit a store, and pick its language from the **Language** sidebar section. Leave it at *Default* to use your Polylang default language. ## Per-Store Language (Pro)[​](#per-store-language-pro "Direct link to Per-Store Language (Pro)") On WCPOS Pro, the plugin adds a **Language** section to the store editor sidebar. Each store can be pinned to a single Polylang language slug — products served to that store are filtered to that language only. Stores left on *Default* use the Polylang default language. The per-store value is saved against the store post as `_wcpos_polylang_language` meta and is exposed via the WCPOS Pro stores REST API (`/wcpos/v1/stores`), so it round-trips through the POS like any other store setting. ## Compatibility Notes[​](#compatibility-notes "Direct link to Compatibility Notes") * **POS-only products:** when POS-only mode is enabled in WCPOS settings, online-only product IDs are excluded from the fast-sync payload so they do not leak into the POS. * **Free installs:** there is no UI for changing the language per store — the plugin uses Polylang's default language. If you need per-store languages, upgrade to [WCPOS Pro](/getting-started/pro-license.md). * **Plugin unavailable:** if Polylang is deactivated, the plugin silently does nothing. It will not throw errors or block the POS. ## Developer Hooks[​](#developer-hooks "Direct link to Developer Hooks") For advanced use, the plugin exposes a few filters: | Filter | Purpose | | ---------------------------------- | ----------------------------------------------------------------------------------------------------- | | `wcpos_polylang_resolved_language` | Override the language used for a given request. Receives the resolved slug and the `WP_REST_Request`. | | `wcpos_polylang_default_language` | Override the fallback language when no per-store value is set. | | `wcpos_polylang_is_supported` | Force the plugin on or off regardless of Polylang detection. | | `wcpos_polylang_minimum_version` | Require a minimum Polylang version (default: no version gate). | ## Requirements[​](#requirements "Direct link to Requirements") WooCommerce : WooCommerce installed and activated Polylang : Polylang (free or Pro) with at least one language configured WCPOS : Free version works; per-store language selection requires WCPOS Pro ## Related[​](#related "Direct link to Related") * [WCPOS WPML](/extensions/wpml.md) * [WCPOS WP Multilang](/extensions/wp-multilang.md) * [Multi-Store](/stores/.md) * Source: [github.com/wcpos/wcpos-polylang](https://github.com/wcpos/wcpos-polylang) --- # WCPOS StoreApps Smart Coupons Adds WCPOS compatibility for store credit created with [Smart Coupons by StoreApps / WooCommerce.com](https://woocommerce.com/products/smart-coupons/). It lets POS orders redeem StoreApps store credit, keeps the StoreApps balance in sync, and leaves an order-note audit trail for staff. This extension is specifically for the StoreApps / WooCommerce.com Smart Coupons plugin. Other plugins with similar “Smart Coupons” names are separate products and may need separate integrations. Pro Feature Installing and managing extensions from the directory requires [WCPOS Pro](/getting-started/pro-license.md). ## What It Does[​](#what-it-does "Direct link to What It Does") * Records the StoreApps `smart_coupons_contribution` metadata for POS-created orders when the normal checkout cart context is not available. * Lets StoreApps deduct the correct partial store-credit amount from the coupon balance after POS checkout. * Restores the StoreApps store-credit balance when the POS order is cancelled or refunded through WooCommerce's normal order lifecycle. * Adds a private order note after redemption showing the coupon code, amount used, and current balance. * Shows the remaining store-credit balance in the existing receipt discount row by appending it to the coupon description/discount label. The extension uses normal WooCommerce coupon fields and metadata. It does not add custom WCPOS coupon response fields or require custom receipt templates. ## Installation[​](#installation "Direct link to Installation") 1 #### Install StoreApps Smart Coupons Install and activate [Smart Coupons by StoreApps / WooCommerce.com](https://woocommerce.com/products/smart-coupons/). Create your store-credit coupons or gift cards as usual in WooCommerce. 2 #### Install WCPOS StoreApps Smart Coupons Install from `WP Admin > POS > Settings > Extensions`, or download the latest release from the [GitHub releases page](https://github.com/wcpos/wcpos-storeapps-smart-coupons/releases) and upload via `Plugins > Add New > Upload Plugin`. 3 #### Sync coupons to the POS Open the POS and sync coupons. Cashiers can then apply StoreApps store-credit coupons from the normal **Add Coupon** flow. ## Receipt Output[​](#receipt-output "Direct link to Receipt Output") WCPOS receipt templates already print coupon discounts using the discount row label. During receipt rendering, this extension appends the current StoreApps balance to that existing label. For example, a coupon description of **Gift card** may print as: ``` Gift card — Store credit balance: £61.50 ``` If the coupon has no description, the balance text is used as the discount label. Existing receipt templates do not need to be changed. ## Order Audit Trail[​](#order-audit-trail "Direct link to Order Audit Trail") After StoreApps processes a POS store-credit redemption, the extension adds a private order note similar to: ``` StoreApps Smart Coupons store credit recorded for WCPOS: Coupon STORE100 used £38.50. Current balance: £61.50. ``` Use this note to confirm which store-credit coupon was used, how much was redeemed, and what balance remained after the sale. ## Compatibility Notes[​](#compatibility-notes "Direct link to Compatibility Notes") * **StoreApps only:** this extension targets StoreApps / WooCommerce.com Smart Coupons. It does not target WebToffee or other smart-coupon plugins. * **Coupon data:** WCPOS continues to use normal WooCommerce coupon responses. StoreApps-specific state remains in WooCommerce metadata such as `smart_coupons_contribution` and coupon balance fields. * **Receipts:** balance text is added through the existing coupon description/discount label path, not by changing receipt data or templates. * **Inactive StoreApps plugin:** if StoreApps Smart Coupons is not active, the extension does nothing. ## Requirements[​](#requirements "Direct link to Requirements") WooCommerce : WooCommerce installed and activated Smart Coupons : Smart Coupons by StoreApps / WooCommerce.com WCPOS : WCPOS with coupon support; extension installation from the directory requires WCPOS Pro ## Related[​](#related "Direct link to Related") * [Coupons](/coupons/.md) * [Applying Coupons at the Till](/coupons/applying-coupons.md) * [Receipt Data](/receipts/receipt-data.md) * Source: [github.com/wcpos/wcpos-storeapps-smart-coupons](https://github.com/wcpos/wcpos-storeapps-smart-coupons) --- # WCPOS WP Multilang Integrates [WP Multilang](https://wordpress.org/plugins/wp-multilang/) with WCPOS so the POS only serves products for a single language. Unlike Polylang or WPML, WP Multilang stores all translations inside the same post — this plugin makes sure WCPOS reads the correct translation and doesn't duplicate entries in search results. ## What It Does[​](#what-it-does "Direct link to What It Does") * Filters WCPOS product and variation REST responses to a single WP Multilang language. * Intercepts WCPOS **fast-sync** routes so only the active language's content reaches the client. * Free installs use the WP Multilang default language. * Pro installs can pin a language per store from the store editor. ## Installation[​](#installation "Direct link to Installation") 1 #### Install WP Multilang Install [WP Multilang](https://wordpress.org/plugins/wp-multilang/) and configure your site languages, with at least one language set as the default. 2 #### Install WCPOS WP Multilang Install from `WP Admin > POS > Settings > Extensions`, or download the latest release from the [GitHub releases page](https://github.com/wcpos/wcpos-wp-multilang/releases) and upload via `Plugins > Add New > Upload Plugin`. 3 #### (Pro) Pin a language per store On WCPOS Pro, edit a store under `POS > Stores` and pick its language from the **Language** sidebar section. Leave at *Default* to use the WP Multilang default language. ## Requirements[​](#requirements "Direct link to Requirements") WooCommerce : WooCommerce installed and activated WP Multilang : WP Multilang with at least one language configured WCPOS : Free version works; per-store language selection requires WCPOS Pro ## Related[​](#related "Direct link to Related") * [WCPOS Polylang](/extensions/polylang.md) * [WCPOS WPML](/extensions/wpml.md) * [Multi-Store](/stores/.md) * Source: [github.com/wcpos/wcpos-wp-multilang](https://github.com/wcpos/wcpos-wp-multilang) --- # WCPOS WPML Integrates [WPML](https://wpml.org/) with WCPOS so the POS only serves products for a single language — translated duplicates stop appearing in product search and the catalog grid. On WCPOS Pro, you can pin a language per store. ## What It Does[​](#what-it-does "Direct link to What It Does") * Filters WCPOS product and variation REST queries to a single WPML language. * Intercepts WCPOS **fast-sync** routes (the lightweight requests the POS uses to refresh its local index) so translated duplicates never reach the client. * Free installs use the WPML default language. * Pro installs can override the language per store from the store editor. ## Installation[​](#installation "Direct link to Installation") 1 #### Install WPML Install and configure [WPML](https://wpml.org/) as normal with at least one language set as the default. 2 #### Install WCPOS WPML Install from `WP Admin > POS > Settings > Extensions`, or download the latest release from the [GitHub releases page](https://github.com/wcpos/wcpos-wpml/releases) and upload via `Plugins > Add New > Upload Plugin`. 3 #### (Pro) Pin a language per store On WCPOS Pro, edit a store under `POS > Stores` and pick its language from the **Language** sidebar section. Leave at *Default* to use the WPML default language. ## Known WPML Compatibility Issues[​](#known-wpml-compatibility-issues "Direct link to Known WPML Compatibility Issues") These are behaviours of WPML itself rather than the integration — worth knowing before rolling out multilingual in production: * **POS custom fields don't carry across translations.** WPML translates products but does not copy WCPOS custom fields to translated versions by default. A product marked "POS Only" in the default language may lose that setting on its translations. Configure WPML to copy WCPOS custom fields during translation. * **POS-only products and 404s on the storefront.** Because WPML generates storefront pages for each language, POS-only products may render as 404s when accessed on the website. This is a known WPML interaction, not a WCPOS bug. See [POS-Only Products](/products/pos-only-products.md) for the related POS visibility controls. ## Requirements[​](#requirements "Direct link to Requirements") WooCommerce : WooCommerce installed and activated WPML : WPML with at least one language configured WCPOS : Free version works; per-store language selection requires WCPOS Pro ## Related[​](#related "Direct link to Related") * [WCPOS Polylang](/extensions/polylang.md) * [WCPOS WP Multilang](/extensions/wp-multilang.md) * [Multi-Store](/stores/.md) * Source: [github.com/wcpos/wcpos-wpml](https://github.com/wcpos/wcpos-wpml) --- # 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[​](#connect-screen-overview "Direct link to 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[​](#adding-a-new-store "Direct link to 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[​](#multiple-stores "Direct link to 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[​](#multiple-users-per-store "Direct link to 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[​](#adding-a-user "Direct link to Adding a User") Click the button next to "Logged in users" to add another user to that store. ### Switching Users[​](#switching-users "Direct link to Switching Users") Click on a user badge (e.g., "Brenda") to open the POS as that user. ### Removing a User[​](#removing-a-user "Direct link to Removing a User") Click the **×** on a user badge to log that user out of the store. ## Removing a Store[​](#removing-a-store "Direct link to 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[​](#demo-store "Direct link to 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[​](#troubleshooting "Direct link to 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](/support/troubleshooting/plugin-conflicts.md#security-and-login-plugins). * **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](/support/performance/server.md#hosting-specific-notes) * Ensure your server meets the [minimum requirements](/support/performance/server.md#minimum-server-requirements) --- # Free vs Pro WCPOS comes in two editions. The **free plugin** is everything you need to take payments at the counter, print receipts, and sync orders back to WooCommerce. **Pro** adds the management screens (Products, Orders, Customers, Reports), more payment gateways, coupons, refunds, and multi-store support. If you mainly need a till that records sales, the free plugin is enough. If you also want to run the day-to-day of your store from the POS — manage stock, look up old orders, refund a customer, accept card payments through an integrated reader — that's what Pro is for. ## At a glance[​](#at-a-glance "Direct link to At a glance") | Area | Free | Pro | | -------------------------------------------------------- | ---- | --- | | Take sales and print/email receipts | | | | Cash and external-card payments | | | | Integrated card readers (Stripe, SumUp, Vipps/MobilePay) | | | | Coupons at the register | | | | Refunds from the POS | | | | Edit stock, prices, and product details from the POS | | | | Look up and reprint historical orders | | | | Add and edit customers | | | | End-of-day reports | | | | Multiple store locations | | | | Per-store receipt templates, tax IDs, and branding | | | | Install and manage POS extensions from settings | | | | Priority Discord support | | | ## What's in the free plugin[​](#whats-in-the-free-plugin "Direct link to What's in the free plugin") The free plugin from [WordPress.org](https://wordpress.org/plugins/woocommerce-pos/) covers the core "ring up a sale" workflow. #### Cash + Card checkout Two built-in payment methods: **Cash** with change calculation, and **Card** for when you take payment on an external terminal and just need to record the sale. #### Cart and product search Search the product panel, scan barcodes, add line items, apply line-item discounts, and add open-priced "Misc" items not in your catalogue. #### Receipts and thermal printing Choose from a built-in [template gallery](/receipts/customise.md) — receipts, invoices, quotes, packing slips, gift receipts, kitchen tickets — and print to 58 mm or 80 mm thermal printers over network, Bluetooth, or USB. #### Offline storage + sync Products and orders are stored locally so the till stays fast and works through a flaky connection. Orders sync back to WooCommerce when the network returns. #### Barcode support Scan products straight into the cart with a USB or Bluetooth scanner, or use the device camera. #### Customer Tax IDs Built-in Tax ID field on the customer record — VAT, ABN, GST, GSTIN, EIN, and other regional formats. #### Cross-platform + multilingual Browser, desktop (Windows/macOS), and mobile apps (iOS/Android, beta). Translated into the major European, Asian, and Latin American languages. POS-only customer/coupon access on Free On the free plugin you can still **select** an existing customer or **see** the Coupons catalogue at the till — you just can't add/edit customers, and you can't apply coupon codes at checkout. Those become available with Pro. ## What Pro adds[​](#what-pro-adds "Direct link to What Pro adds") Pro unlocks the rest of the back-office, more payment options, and per-store features. Every item below is Pro-only. ### Management screens[​](#management-screens "Direct link to Management screens") The free plugin gives you a Product Panel for ringing up sales. Pro adds the full management surface: | Screen | What you can do | | ------------------------------- | ------------------------------------------------------------------------------------------------------------ | | **[Products](/products/.md)** | Edit stock levels, prices, and cost of goods sold inline. Bulk operations across the catalogue. | | **[Orders](/orders/.md)** | Look up historical orders, reprint receipts, edit orders, and access the refund flow. | | **[Customers](/customers/.md)** | Add new customers and edit existing customer details (free users can only select from a picker at checkout). | | **[Reports](/reports/.md)** | End-of-day sales reports — totals by payment method, cashier, and store, suitable for cash reconciliation. | | **[Coupons](/coupons/.md)** | Browse the WooCommerce coupon catalogue from the till (free users see a blurred preview only). | ### Payment gateways[​](#payment-gateways "Direct link to Payment gateways") The free plugin's "Card" gateway just records a sale that you took on an external terminal — there's no integration with the reader itself. Pro lets you use **any WooCommerce payment gateway** at the POS, and bundles several integrated gateways: | Gateway | Use case | | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | **[Stripe Terminal](/payment/gateways/stripe-terminal.md)** | Direct integration with Stripe's S700 / WisePOS E readers. Supports MOTO (phone orders) and a simulator for testing. | | **[SumUp Terminal](/payment/gateways/sumup-terminal.md)** | Pair a SumUp card reader to the POS and complete card payments without leaving the till. | | **[Vipps MobilePay](/payment/gateways/vipps-mobilepay.md)** | Phone-based payments via QR code or push notification — Vipps in Norway, MobilePay in Denmark and Finland. | | **[Email Invoice](/payment/gateways/email-invoice.md)** | Send the customer a payment link by email; the order completes when they pay online. | | **[Web Checkout](/payment/gateways/web-checkout.md)** | Redirect the customer to your hosted checkout to complete payment online. | | **Any other WooCommerce gateway** | Use the [Gateway Template](/payment/gateways/.md) to wrap any WooCommerce payment plugin for POS checkout. | ### Coupons, refunds, and the at-counter workflow[​](#coupons-refunds-and-the-at-counter-workflow "Direct link to Coupons, refunds, and the at-counter workflow") #### Coupons at the register Search and apply WooCommerce coupon codes at checkout. Coupons appear as removable pills in the cart, support sequential discounts, and respect all the usual rules — expiry, usage limits, min/max spend, product and category restrictions. #### Refunds at the till Issue full or partial [refunds](/orders/refunds.md) from the POS — refund to the original payment method or as cash. Cashier and store are recorded on the refund for a full audit trail. ### Multi-store, stock, and branding[​](#multi-store-stock-and-branding "Direct link to Multi-store, stock, and branding") #### Multi-store locations Create multiple [store locations](/stores/.md), each with its own address, logo, tax rates, [tax IDs](/settings/wp-admin/store-tax-ids.md), and cashier assignments. Orders and reports can be filtered per store. #### Per-location inventory (ATUM) Link Pro stores to [ATUM Multi-Inventory](/extensions/atum.md) locations for per-location stock, pricing, and SKUs. #### Per-store receipt templates Assign different receipt and invoice [templates](/receipts/.md) to different stores. Each store has its own branding — logo, address, contact details — and template ordering. #### Install POS extensions Install, activate, and update POS [extensions](/extensions/.md) and integrations directly from the settings screen. Free users see the catalogue but the install controls are disabled. ### Support[​](#support "Direct link to Support") * **Priority Discord support** — one-on-one assistance via a private channel, in addition to the public community channels. ## Pricing[​](#pricing "Direct link to Pricing") Pro is sold per site from [wcpos.com/pro](https://wcpos.com/pro): * **Annual licence** — $129 / year, includes updates and support for the licence term. * **Lifetime licence** — $399 one-time, includes updates and support for the lifetime of the product. Prices current as of May 2026; subject to change. When a licence expires, Pro features keep working but you stop receiving updates and support. See [Installing WCPOS Pro](/getting-started/pro-license.md) for activation steps and licence troubleshooting. Still deciding? You can try the public demo at [demo.wcpos.com/pos](https://demo.wcpos.com/pos) (login `demo` / `demo`) — it runs the full Pro feature set so you can see the management screens, coupons, and refund flow before buying. ## Ready to upgrade?[​](#ready-to-upgrade "Direct link to Ready to upgrade?") Head over to [Installing WCPOS Pro](/getting-started/pro-license.md) for download and activation steps. * **v1.8+ Pro** — deactivate and delete the free plugin first. From v1.8 onwards, Pro is a standalone plugin that should not be installed alongside the free version. * **Older Pro (< v1.8)** — keep the free plugin installed if your Pro version requires it. --- # Installation Requirements To ensure proper functionality and optimal performance of the WCPOS plugin, please make sure your environment meets the following minimum requirements: ## Server Requirements[​](#server-requirements "Direct link to Server Requirements") The WCPOS plugin runs on your WordPress site, which must meet these minimums: | Component | Minimum version | Notes | | ----------- | --------------- | --------------- | | WordPress | 5.6 | — | | WooCommerce | 5.3 | — | | PHP | 7.4 | 8.x recommended | Meeting these minimums ensures compatibility and stability with your WordPress environment, and access to the latest WCPOS features. ## Browser Requirements[​](#browser-requirements "Direct link to Browser Requirements") The web version of the POS runs in any modern browser. Use the latest stable release: | Browser | Supported version | | --------------- | ----------------- | | Google Chrome | Latest stable | | Mozilla Firefox | Latest stable | | Safari | Latest stable | | Microsoft Edge | Latest stable | Avoid private / incognito mode Private browsing can block access to the browser's IndexedDB database, which WCPOS uses to store data offline — some features will not work correctly. JavaScript must also be enabled. ## App Requirements[​](#app-requirements "Direct link to App Requirements") WCPOS is also available as a desktop and mobile app. Each is built for the following minimum operating systems: | Platform | Minimum OS | Architectures | | --------------- | ------------------------- | -------------------------- | | Windows desktop | Windows 10 | x64, ARM64 | | macOS desktop | macOS 12 (Monterey) | Intel (x64), Apple Silicon | | iOS / iPadOS | iOS 16.4 | — | | Android | Android 10 (API level 29) | — | Printing permissions Bluetooth and network printing require granting the app the relevant Bluetooth and local network permissions when prompted. ## Installing the Plugin[​](#installing-the-plugin "Direct link to Installing the Plugin") 1. Go to `WP Admin > Plugins > Add Plugin` 2. Search for "wcpos" 3. Click **Install Now**, then **Activate** Alternatively, you can download the plugin from [WordPress.org](https://wordpress.org/plugins/woocommerce-pos/) and upload it manually. ## Accessing the POS[​](#accessing-the-pos "Direct link to Accessing the POS") After activation, you can access the POS at: * **Web:** `yourdomain.com/pos` * **Desktop:** [Windows](https://updates.wcpos.com/electron/download/win32-x64), [Mac (Intel)](https://updates.wcpos.com/electron/download/darwin-x64), [Mac (Apple Silicon)](https://updates.wcpos.com/electron/download/darwin-arm64) * **Mobile:** [iOS](https://testflight.apple.com/join/JGBdVRrW), [Android](https://play.google.com/apps/testing/com.wcpos.main) By meeting the minimum requirements and using a compatible web browser, you can have a seamless experience using the WCPOS plugin and leverage its full potential to manage your point of sale operations efficiently. If you have any further questions or need assistance, please don't hesitate to reach out to our support team by posting them to the [Discord chat](https://wcpos.com/discord) or emailing them to . --- # Offline Functionality WCPOS stores your product and customer data locally on each device using a browser-based database (IndexedDB). This means parts of the POS work without an internet connection, while others require connectivity. ## What Works Offline[​](#what-works-offline "Direct link to What Works Offline") * **Browsing products** — search, filter, and view product details from cached data * **Browsing customers** — look up customer names, emails, and addresses * **Building a cart** — add items, change quantities, edit prices, and apply POS discounts * **Barcode scanning** — scan barcodes to find products in the local database * **Viewing reports** — the default (offline) report type generates reports from locally stored orders ## What Requires a Connection[​](#what-requires-a-connection "Direct link to What Requires a Connection") * **Completing checkout** — processing payment and creating the order in WooCommerce requires server communication * **Applying coupon codes** — coupon validation happens on the server * **Syncing data** — pulling new products, updated prices, or new customers from WooCommerce * **Logging in** — initial authentication requires a connection to your WordPress site * **Licence activation** — Pro licence checks need to reach the WCPOS licence server * **Processing refunds** — refunds can't be queued offline; the gateway and your store both need to be reachable (see [Refunds](/orders/refunds.md)) ## How the Local Database Works[​](#how-the-local-database-works "Direct link to How the Local Database Works") When you first open WCPOS, it begins downloading your WooCommerce products and customers in the background. This process is progressive — the more you use the POS, the more complete your local data becomes. The local database: * **Persists between sessions** — data survives browser restarts and device reboots * **Is per-device** — each device maintains its own local copy * **Stays in sync** — WCPOS periodically checks for changes on the server and pulls updates For more technical detail, see the [Architecture](/reference/architecture.md) reference. ## Connectivity Indicator[​](#connectivity-indicator "Direct link to Connectivity Indicator") The POS header shows a coloured dot indicating connection status: * **Green** — connected to the server, all features available * **Yellow** — intermittent connection, some operations may be slow * **Red** — offline, limited to browsing cached data ## What Happens During Connectivity Loss[​](#what-happens-during-connectivity-loss "Direct link to What Happens During Connectivity Loss") If you lose your internet connection while using the POS: 1. **Products and customers remain browsable** from cached data. 2. **You can continue building carts** and editing items. 3. **Checkout will fail** if attempted — the POS needs to reach your WooCommerce server to process the order. 4. **Open orders are preserved** in the local database until connectivity returns. ## When Connection Restores[​](#when-connection-restores "Direct link to When Connection Restores") Once your connection comes back: * The connectivity indicator turns green. * You can proceed to checkout and complete any parked orders. * Background sync resumes, pulling any product or customer changes that happened while you were offline. * No manual action is required — WCPOS handles reconnection automatically. ## Tips for Unreliable Connections[​](#tips-for-unreliable-connections "Direct link to Tips for Unreliable Connections") * **Use "Save to Server" on important orders** — this pushes the order to WooCommerce immediately, so it's not lost if the device's local database is cleared. * **Sync regularly** — if you know connectivity is intermittent, sync your product catalogue while you have a good connection so local data is up to date. * **Consider the native apps** — the desktop and mobile apps (when available) can offer better offline resilience than the browser version. --- # Re-Installing a Previous Version of the WCPOS Plugin ## Re-Installing a Previous Version[​](#re-installing-a-previous-version "Direct link to Re-Installing a Previous Version") If you need to revert to a previous version of the WCPOS plugin, follow these steps: 1. Visit the WordPress.org page [Advanced View](https://wordpress.org/plugins/woocommerce-pos/advanced/) for WCPOS. 2. Scroll down to the **Advanced Options** section and locate **Previous Versions** select menu. 3. Open the select menu and you will see a list of available plugin versions. Find the version you want to install and click on the **Download** button next to it. Save the downloaded file to your desktop or a convenient location. ![Advanced Options](https://wcpos.com/wp-content/uploads/2023/06/advanced-options.png) [](https://wordpress.org/plugins/woocommerce-pos/advanced/) [Advanced View](https://wordpress.org/plugins/woocommerce-pos/advanced/) for WCPOS 4. Log in to your WordPress Admin dashboard. 5. Navigate to the **Plugins** page by clicking on **Plugins** in the left-hand menu. 6. Deactivate and delete the current version of the WCPOS plugin. This will remove the plugin from your WordPress installation. Don't worry, your data will not be lost. 7. Click on the **Add Plugin** button at the top of the page. 8. On the **Add Plugins** page, click on the **Upload Plugin** button. 9. Choose the previously downloaded plugin file from your desktop or the location where you saved it. ![Upload Plugin](https://wcpos.com/wp-content/uploads/2023/06/upload-plugin.png) Upload plugin in the WordPress Admin 10. Click on the **Install Now** button and wait for the installation to complete. 11. After the installation is finished, click on the **Activate** button to activate the previous version of the WCPOS plugin. That's it! You have successfully re-installed a previous version of the WCPOS plugin. If you encounter any issues during the re-installation process or need further assistance, please contact our support team at . --- # Installing WCPOS Pro Pro Feature [WCPOS Pro](https://wcpos.com/pro) is a paid plugin that powers the management screens, additional payment gateways, and other Pro-only features in WCPOS. **As of v1.8+, Pro is a standalone plugin** — you do not need the free [WCPOS plugin](https://wordpress.org/plugins/woocommerce-pos/) installed alongside it. ## What's Included in Pro?[​](#whats-included-in-pro "Direct link to What's Included in Pro?") WCPOS Pro unlocks additional features: * **Products Screen** - Edit stock levels and prices directly in the POS * **Orders Screen** - View and manage order history * **Customers Screen** - Add and edit customer information * **Reports Screen** - Generate end-of-day sales reports * **Additional Payment Gateways** - Stripe Terminal, SumUp, and custom gateways ## Installation[​](#installation "Direct link to Installation") If you have purchased a license for WCPOS Pro please follow the steps below to install and activate the plugin: Upgrading from older versions? If you previously had both the free WCPOS plugin and an older Pro add-on installed, **deactivate and delete the free plugin** before activating the new standalone Pro plugin. Running both side-by-side can cause activation errors such as *"Invalid response fetching remote state"* or fatal *"Class not found"* errors. 1. Go to: 2. Under **Downloads**, click the download link and save the plugin to your desktop. 3. Then go to your site, login and go to `WP Admin > Plugins > Add Plugin > Upload Plugin` 4. Upload the plugin zip file from your desktop and activate. 5. Next, go to `WP Admin > POS > Settings > License` and enter your License Key and License Email to complete the activation. ![My Downloads](https://wcpos.com/wp-content/uploads/2014/07/my-download.png "You can download WCPOS Pro on your account page") ## Updates[​](#updates "Direct link to Updates") When new versions are ready they will appear in your Updates dashboard like any other plugin. You can also download the latest version from your [account page](https://wcpos.com/my-account/). ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Activation Failures[​](#activation-failures "Direct link to Activation Failures") * **"Invalid licence key"** — double-check for trailing spaces when pasting, and confirm the email address matches the one used at purchase. * **"Licence limit reached"** — by default a licence activates on **2 domains** (intended for one live site and one staging site). Note that **subdomains count as separate activations** — `example.com`, `staging.example.com`, and `dev.example.com` are three. This often catches hosts like Pantheon with mandatory dev/test/live environments. Deactivate unused sites from your [account page](https://wcpos.com/my-account/), or email **** — extra activations are routinely granted on request. ### Expired Licence[​](#expired-licence "Direct link to Expired Licence") * When a licence expires, Pro features remain active but you won't receive updates. * Renew from your [account page](https://wcpos.com/my-account/) — the existing key stays the same. ### Domain Transfers[​](#domain-transfers "Direct link to Domain Transfers") * If you've moved your site to a new domain, deactivate the licence on the old domain first, then reactivate on the new one. * If the old domain is no longer accessible, contact **** to reset the activation. ### Licence Server Connectivity[​](#licence-server-connectivity "Direct link to Licence Server Connectivity") * Activation requires your WordPress server to reach the WCPOS licence server. * If activation fails silently, check that outbound HTTPS requests aren't blocked by your host's firewall or a security plugin. * Some managed hosts block external API calls by default — contact your host to whitelist `wcpos.com`. ### Checking Licence Status[​](#checking-licence-status "Direct link to Checking Licence Status") * Go to `WP Admin > POS > Settings > License` to see your current activation status. * Your [account page](https://wcpos.com/my-account/) shows all active sites and expiry date. ## Purchase a License[​](#purchase-a-license "Direct link to Purchase a License") Visit [wcpos.com/pro](https://wcpos.com/pro) to purchase a Pro license. Buying and upgrading happen on the website There's no in-app "upgrade to Pro" button — purchases, plan upgrades, and renewals are all handled on [wcpos.com](https://wcpos.com/pro) and your [account page](https://wcpos.com/my-account/). After buying, install Pro using the [steps above](#installation). --- # Roadmap WCPOS is under active development. This page is the single place to check **what's coming**, follow progress, and tell us what you need. ## The public roadmap[​](#the-public-roadmap "Direct link to The public roadmap") The live, always-current source of truth is our public roadmap board on GitHub. It shows what's in progress, what's up next, and the wider backlog: [WCPOS Roadmap on GitHub →In progress, up next, and backlog — updated continuously as work moves.](https://github.com/orgs/wcpos/projects/4) Direction, not promises The roadmap reflects what we're working on and exploring — **not committed dates or guarantees**. Priorities shift based on what users need most. If a feature is critical to you, tell us (below) — demand is the biggest factor in what we build next. ## Request or vote on a feature[​](#request-or-vote "Direct link to Request or vote on a feature") The best way to influence what we build is to ask: * **[Discord](https://wcpos.com/discord)** — the fastest way to reach us and the community. Share your use case in `#general` or `#forum`. * **[GitHub Discussions](https://github.com/orgs/wcpos/discussions)** — propose a feature or add your "+1" and use case to an existing one. Many roadmap items started as a discussion. When you ask, tell us *what you're trying to do* and *why* — concrete use cases shape the design far more than a feature name. ## What we're working on[​](#what-were-working-on "Direct link to What we're working on") A high-level view of the themes in development. For the detailed, current status of any item, check the [roadmap board](https://github.com/orgs/wcpos/projects/4). ### At the register[​](#at-the-register "Direct link to At the register") * **Stock control** — prevent overselling by blocking out-of-stock items at the cart and validating stock at checkout * **Checkout conditions** — require things like a customer, an order note, or a custom field before an order can be completed * **Split & partial payments** — pay a single order with more than one method (e.g. part cash, part card) * **Cash management** — opening cash float, and formal shift start/stop for accurate end-of-day reporting ### Reporting & documents[​](#reporting-and-documents "Direct link to Reporting & documents") * **Reporting templates** — configurable Z-reports and shift summaries, printable to A4 or thermal * **Email templates** — POS-specific email/receipt layouts, separate from your standard order emails ### Selling more product types[​](#selling-more-product-types "Direct link to Selling more product types") Compatibility with more WooCommerce extensions — **Product Add-Ons**, **Product Bundles**, **Composite Products**, **Bookings**, **Product Options**, and **embedded (scale) barcodes**. ### Hardware & displays[​](#hardware-and-displays "Direct link to Hardware & displays") * **More card readers** and direct reader integrations * **Customer-facing display** — a second screen showing the order and total to the customer * **Order notifications** — real-time alerts for new online orders (great for restaurants) ## Already shipped[​](#already-shipped "Direct link to Already shipped") Recently landed highlights — see the docs for each: [Coupons at the tillSearch, apply, and stack coupons during a sale.](/coupons/.md) [RefundsProcess refunds to the original method or cash.](/orders/refunds.md) [Cloud printingPrint to printers that aren't attached to the till.](/receipts/cloud-printing.md) [Thermal receiptsDesign ESC/POS and Star thermal layouts.](/receipts/thermal-templates.md) --- # Hardware WCPOS works with the physical devices you already use at the counter. This page is the starting point for connecting hardware — receipt printers, barcode scanners, card readers, and cash drawers. Each device type either has its own setup page here, or points to the page where its setup actually lives. ## Devices[​](#devices "Direct link to Devices") [Receipt PrintersConnect a thermal or network printer over USB, Bluetooth, or the network. Covers Epson, Star, and generic printers.](/hardware/printers.md) [Barcode ScannersUse a USB, Bluetooth, or camera-based scanner to add products to the cart and look up items.](/pos/product-panel/barcode-scanning.md) [Card Readers & TerminalsCard readers are set up with their payment gateway — see Stripe Terminal, SumUp, and the other gateway guides under Payment Gateways.](/payment/gateways/.md) [Cash DrawersA cash drawer is kicked open by the receipt printer it's wired to — set it up on the Receipt Printers page.](/hardware/printers.md#cash-drawers) One home per device The Hardware hub points you to each device's setup, but the actual steps live in a single place. A card reader's account and pairing flow lives on its Payment Gateway page; a cash drawer's kick setting lives on the Receipt Printers page. ## Card reader compatibility[​](#card-reader-compatibility "Direct link to Card reader compatibility") Which card readers work depends on **how you run WCPOS** and on the reader's connection type: * **The web app** can only drive readers that offer a **web (browser) SDK** — typically internet-connected countertop terminals. **Bluetooth-only** readers (e.g. Stripe M2 / WisePad 3, SumUp Air) and phone **Tap-to-Pay** are **not supported** in the web app. * Support is **per gateway**, not universal — check the reader against the gateway you plan to use ([Stripe Terminal](/payment/gateways/stripe-terminal.md), [SumUp](/payment/gateways/sumup-terminal.md), [PayPal Reader](/payment/gateways/paypal-reader.md)) before buying. Each gateway page lists the exact readers it supports. --- # Printer Setup Printer settings are found under **POS > Settings > Printing**. Each device manages its own printer configuration — printers are stored locally and not synced between devices. Printing to a printer that isn't on this device? This page covers printers attached to the till by USB, Bluetooth, or the local network. For a printer in another room or location — or one you want every device to share — see [Cloud Printing](/receipts/cloud-printing.md). Cloud printers you've set up for your store appear **automatically** in every device's printer list — you don't add them here. ## Supported Printers by Platform[​](#supported-printers-by-platform "Direct link to Supported Printers by Platform") The **Add Printer** form adapts to the app you're using — each platform shows only the connections and options it can actually use. | Platform | Supported Printers | Connections | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- | | **Web app** | Epson and Star printers with a built-in web server (network); Epson and Star printers via WebUSB/Web Bluetooth (USB/Bluetooth, Chrome/Edge only) | Network (HTTP), USB, Bluetooth | | **Desktop app** | Any network receipt printer | Network (raw TCP), USB, Bluetooth | | **iOS app** | Epson and Star | Network, Bluetooth | | **Android app** | Epson and Star | Network, Bluetooth, USB | Why only Epson and Star over the network on the web? Web browsers cannot open raw TCP connections. Epson and Star receipt printers include a built-in web server that accepts print jobs over HTTP — this is the only way to send ESC/POS commands to a *network* printer from a browser. The desktop app doesn't have this limitation because it can connect directly over TCP. USB and Bluetooth printing in the browser work too, but only in **Chrome or Microsoft Edge** (they use the WebUSB and Web Bluetooth APIs) — Safari and Firefox don't support them. On the **mobile apps**, Bluetooth and USB printing go through Epson's and Star's official SDKs, so those connections require an Epson or Star printer. Generic printers work over the network only. ## Adding a Printer[​](#adding-a-printer "Direct link to Adding a Printer") 1 #### Open Printer Settings Go to **POS > Settings > Printing**. If no printers are configured yet, you'll see an empty state with an **Add Printer** button. Every printer gets a **Printer Name** — just a label, auto-filled as "Receipt Printer" (then "Receipt Printer 2", and so on) — which you can change to anything that helps you tell your printers apart. 2 #### Choose How the Printer Connects Every platform starts with the same question — **Connection Type** — and shows only the options that platform supports. The fields below update to match your choice. * **Web app** — **Network**, **USB**, or **Bluetooth** (USB and Bluetooth need Chrome or Edge). For a **Network** printer you then choose the **Vendor** — Epson or Star — because the browser reaches a network printer through that brand's built-in web server. * **Desktop app** — **Network**, **USB**, or **Bluetooth**. * **Mobile apps** — **Network** or **Bluetooth**, plus **USB** on Android (iOS has no USB support). 3 #### Identify the Printer **Network printers** — enter the **IP Address** (for example `192.168.1.100`). WCPOS probes the address to detect whether it's an Epson or Star device, and auto-fills the port, command language, and vendor. You'll see a "Detected: Epson" or "Detected: Star" label once detection completes. On the web app, it also shows the exact endpoint URL it will connect to. **Bluetooth or USB printers** (mobile) — pick your printer from the discovered-device list. Selecting a device fills in its name and vendor automatically. Tap **Scan for printers** (Bluetooth) or **Refresh** (USB) if your printer isn't listed yet. If automatic detection doesn't get everything right, you can adjust it all under **Advanced Settings**. 4 #### Save and Test Click **Save**. WCPOS sends a **test print** first, and only saves the printer if it succeeds. The test print is a short diagnostic — a numbered column ruler, centered normal and double-size text, a left/right alignment row, and a paper cut. It's designed so you can confirm the paper width, alignment, sizing, and cut are all configured correctly, not just that the printer is reachable. Test fails? You can still save If the test fails, you'll see the error along with a **Save without testing** option to save the profile anyway. ## Connection Types[​](#connection-types-mobile-apps "Direct link to Connection Types") You start by picking the **Connection Type** at the top of the Add Printer form, and the connection fields update to match. The types available depend on the platform (see the table above). ### Network[​](#network "Direct link to Network") The printer is on the same Wi-Fi network as your device. On the **desktop** and **mobile** apps, tap **Scan Network** to discover printers automatically, or enter the IP address manually — see [Finding Your Printer's IP Address](#finding-your-printers-ip-address). The **web app** uses manual IP entry only. On the desktop and mobile apps a network printer can be Epson, Star, or Generic; on the web it must be **Epson or Star**, and you pick which under the Network connection. ### Bluetooth[​](#bluetooth "Direct link to Bluetooth") The printer is paired to your device over Bluetooth. Choose yours from the list — its name and vendor fill in automatically. On **mobile**, Bluetooth printing uses Epson's and Star's native SDKs, so the printer must be an **Epson or Star** model; on the **web**, Bluetooth works in Chrome or Edge via the Web Bluetooth API. ### USB[​](#usb-android-only "Direct link to USB") The printer is connected by a USB cable. Pick it from the connected-device list. USB is available on the **web** (Chrome or Edge, via WebUSB), the **desktop** app, and **Android** — but **not iOS**, which has no general USB peripheral support. On mobile, USB printing requires an **Epson or Star** printer. note The **Port** setting only applies to network printers — it's hidden for Bluetooth and USB connections. ## Advanced Settings[​](#advanced-settings "Direct link to Advanced Settings") Expand **Advanced Settings** to fine-tune the printer configuration. Most of these are filled in automatically once the vendor is known. These settings apply on every platform: | Setting | Options | Description | | ----------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Language** | ESC/POS, StarPRNT, Star Line Mode | The command protocol the printer speaks. Auto-filled from the detected vendor. | | **Printer text width** | 58mm (32 chars), 80mm standard (42 chars), 80mm wide (48 chars) | How many characters fit on a line. Match this to your paper and printer — most 80mm printers are 42 characters per line, some are 48. | | **Full receipt raster** | Off / On | Print the whole receipt as an image instead of text — see [Full receipt raster](#full-receipt-raster) below. | These two settings behave differently depending on the platform and connection type: | Setting | Options | Where it applies | | ---------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Vendor** | Epson, Star, Generic | Printer manufacturer. On the **web app** you pick the vendor directly under the **Network** connection (Epson or Star only), not as an advanced setting. Generic is available for **network** printers on the desktop and mobile apps, but not for Bluetooth or USB connections. | | **Port** | Auto-filled | Network port for the printer, shown next to the IP address. **Network only** — hidden for Bluetooth and USB. It's filled in for you based on the vendor (and, on the web, whether your POS is served over HTTP or HTTPS); change it only if your network remaps it. | ## Printer Options[​](#printer-options "Direct link to Printer Options") These toggles sit at the bottom of the Add Printer form: | Option | Description | | ------------------------- | -------------------------------------------------------------------------------------------- | | **Auto-cut paper** | Cut the paper automatically after each receipt | | **Auto-open cash drawer** | Send a kick command to open a connected cash drawer after printing | | **Set as default** | Make this the default printer — used for any receipt that isn't routed to a specific printer | Looking for "auto-print after checkout"? Automatically printing a receipt when a sale completes is a **cart setting**, not a printer setting — turn on **Auto-print receipt** in the POS cart settings. *Which* printer it uses is decided by your default printer and any per-template printer routing. ## Print routing[​](#print-routing "Direct link to Print routing") If you use more than one template — say a thermal receipt **and** an A4 invoice — print routing decides which printer each template prints to. Routing has three layers, checked in this order: 1. **Per-job override.** On the receipt screen, a printer dropdown sits next to the template switcher. Picking a printer here overrides everything for that one print job. Switching templates resets it back to **Auto**. 2. **Settings override.** Go to **POS > Settings > Printing**, then use the **Receipt templates** section to assign a specific printer to each template. For example, route your thermal receipt to the Epson network printer and your HTML invoice to the system print dialog. Set a template back to **Auto** to remove the override. 3. **Auto-match.** When no override is set, WCPOS matches automatically: * **Thermal templates** route to thermal printers whose character width matches. A 58mm thermal template prefers 32-column printers; an 80mm template prefers 42- or 48-column printers. * **HTML templates** route to the system print dialog. * If multiple printers match, the **default** printer wins. If you manually send a template to an incompatible printer — say, a thermal template to the system dialog — an amber **mismatch warning** appears on the receipt screen. The print still proceeds but the output may not render correctly. Routing overrides are stored **per device**. Each iPad, phone, or computer manages its own routing — there is no server-side sync. note The **Receipt templates** printer controls under **POS > Settings > Printing** only appear once you've added at least one printer. With no printers configured, every template uses the system print dialog implicitly. **Cloud printers** set up for your store count here too — they appear as routing targets automatically, without being added on the device. ## Full receipt raster[​](#full-receipt-raster "Direct link to Full receipt raster") By default, WCPOS sends receipts to thermal printers as **text** — fast, compact, and crisp, using the printer's built-in fonts. The catch: thermal printer fonts only cover a limited set of characters. Scripts the printer has no font for — many non-Latin alphabets, right-to-left text, some symbols — can come out as blank boxes or garbled characters. **Full receipt raster** fixes this. When it's on, WCPOS renders the whole receipt as an image and sends that image to the printer, so the printout matches exactly what's on screen — in any language or script. Turn it on per-printer under **Advanced Settings**. Things to know: * **It's slower.** An image is much larger than a line of text, so the receipt takes longer to send and print. * **Use it only when you need it.** If your receipts print fine as text, leave it off. * It applies to thermal printers on any connection (network, Bluetooth, USB). It doesn't apply to the system print dialog, which already prints from a full-page rendering. ## Discovering Printers[​](#discovering-printers "Direct link to Discovering Printers") How you find a printer depends on the connection: * **Bluetooth and USB** — on the **mobile apps**, tap **Scan for printers** (Bluetooth) or **Refresh** (USB) and pick yours from the list; its name and vendor fill in automatically. On the **web** (Chrome or Edge), click **Connect** and choose the printer from the browser's own device chooser. * **Network** — on the **desktop** and **mobile** apps, tap **Scan Network** to find printers on your local network automatically (the desktop discovers them over mDNS/Bonjour; mobile uses the Epson and Star SDKs), then pick yours from the list. You can also enter the IP address directly — see [Finding Your Printer's IP Address](#finding-your-printers-ip-address) below. Browsers can't scan networks, so the **web app** always uses manual IP entry. ## Finding Your Printer's IP Address[​](#finding-your-printers-ip-address "Direct link to Finding Your Printer's IP Address") Most receipt printers can print a self-test page that includes the IP address: * **Epson**: Hold the feed button while powering on * **Star**: Hold the feed button for 5 seconds while powered on Alternatively, check your router's connected-devices list or your printer's configuration utility. ### Static IP Recommended[​](#static-ip-recommended "Direct link to Static IP Recommended") Receipt printers should use a **static IP address** to prevent the address from changing when the printer restarts. Configure this either: * In your printer's built-in web interface (usually accessible at `http://`) * In your router's DHCP settings (assign a reserved IP to the printer's MAC address) ## Epson Printers[​](#epson-printers "Direct link to Epson Printers") Epson printers with ePOS support communicate over HTTP. WCPOS sends SOAP/XML requests to the printer's built-in web server. **Connection details:** * Port `8008` (HTTP) or `8043` (HTTPS) — auto-filled to match whether your POS is served over HTTP or HTTPS * Endpoint: `/cgi-bin/epos/service.cgi` **Confirmed working models:** * Epson TM-T70-i 2 (network) * Epson TM-m30iii (with Printus middleware) tip Make sure your Epson printer has ePOS enabled in its configuration. Access the printer's web interface at `http://` to check and enable ePOS settings. On the **mobile apps**, Epson printers can also connect over Bluetooth or USB through Epson's native SDK — no IP address or ePOS web server required. ## Star Printers[​](#star-printers "Direct link to Star Printers") Star printers with WebPRNT support communicate over HTTP. WCPOS sends commands to the Star WebPRNT endpoint. **Connection details:** * Port `80` (HTTP) or `443` (HTTPS) — auto-filled to match whether your POS is served over HTTP or HTTPS * Endpoint: `/StarWebPRNT/SendMessage` On the **mobile apps**, Star printers can also connect over Bluetooth or USB through Star's native SDK. ## Generic Printers[​](#generic-printers "Direct link to Generic Printers") The **desktop app** supports any network receipt printer via raw TCP. Enter the printer's IP address and port (usually `9100`). This works with most thermal printers regardless of manufacturer, as long as they accept ESC/POS commands. On the **mobile apps**, Generic printers are also supported — but for **network** connections only, not over Bluetooth or USB (those require an Epson or Star printer). The **web app** does not support Generic printers at all. ## Cash Drawers[​](#cash-drawers "Direct link to Cash Drawers") Cash drawers connected to a receipt printer can be triggered automatically after each sale: 1. Enable **Auto-open cash drawer** in the printer options 2. The POS sends an ESC/POS kick command after printing note Cash drawer control requires a thermal printer profile — the browser print dialog cannot trigger cash drawers. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") Printer not detected during setup * Confirm the printer is powered on and connected to the same network as your device * For network printers: on the desktop or mobile app, try **Scan Network** to find it automatically; otherwise check the IP address is correct (print a self-test page) * For the web app: confirm the printer is an Epson or Star model with ePOS/WebPRNT support * For the desktop app: try the Generic vendor option with port 9100 * For Bluetooth: pair the printer in your device's Bluetooth settings first, then tap **Scan for printers** * For USB (Android): check the cable and approve the USB permission prompt if one appears * Check that no firewall is blocking the connection Printer detected but nothing prints * Check the paper roll — it may be empty or jammed * Verify the **Printer text width** setting matches your paper (58mm or 80mm) * Try printing a self-test from the printer itself to confirm it works * Check the command language matches your printer (ESC/POS for Epson, StarPRNT or Star Line Mode for Star) Receipt is garbled or has wrong characters * The command language setting may be wrong — try switching between ESC/POS, StarPRNT, and Star Line Mode * Make sure the **Printer text width** setting is correct * If the receipt is in a non-Latin script or a right-to-left language, turn on **Full receipt raster** in Advanced Settings — it prints the receipt as an image so any language renders correctly Cash drawer doesn't open * Confirm **Auto-open cash drawer** is enabled in the printer options * Check the drawer is connected to the printer's DK port (not a separate power source) * Not all printers support the drawer kick command — consult your printer's documentation Cannot connect from the web app * Over the **network**, the web app reaches only Epson and Star printers (through their built-in web servers) — generic raw-network printers aren't supported in a browser; use the desktop or mobile app, or a [cloud printer](/receipts/cloud-printing.md) * **USB and Bluetooth** printers do work on the web, but only in **Chrome or Microsoft Edge** (Safari and Firefox don't support the WebUSB / Web Bluetooth APIs) * If your site uses HTTPS but the printer only speaks HTTP, the browser may block the connection as mixed content — the printer must use the same HTTP/HTTPS as your POS Bluetooth printer won't connect (mobile) * Pair the printer in your device's system Bluetooth settings before adding it in WCPOS * Bluetooth printing supports Epson and Star printers only — Generic Bluetooth printers aren't supported * If the printer doesn't appear in the list, tap **Scan for printers** again and make sure it's powered on and in range --- # Orders Pro Feature The Orders screen requires [WCPOS Pro](/getting-started/pro-license.md). The Orders screen provides access to your order history directly within the POS. View past orders, reprint receipts, and manage order details without switching to the WooCommerce admin. ## Interface Overview[​](#interface-overview "Direct link to Interface Overview") ### Search & Filters[​](#search--filters "Direct link to Search & Filters") At the top of the screen: * **Search bar** - Find orders by number, customer name, etc. * **Status filter** - Filter by order status (Completed, Processing, etc.) * **Customer filter** - Filter by customer * **Cashier filter** - Filter by who processed the order * **Store filter** - Filter by store (for multi-store setups) * **Date Range** - Filter by date Active filters appear as blue badges that can be removed by clicking the ×. ### Orders Table[​](#orders-table "Direct link to Orders Table") The main area displays orders with: * **Status icon** - Visual indicator (✓ completed, 🕐 pending, 🛒 open) * **Order Number** - Unique order ID * **Customer** - Customer name (or "Guest") * **Billing Address** - Customer billing information * **Note indicator** - Speech bubble when order has notes * **Date Created** - Relative timestamps ("2 hours ago") * **Cashier** - Who processed the order * **Payment Method** - Cash, Card, etc. * **Total** - Order total amount * **Actions** - Three-dot menu ### Footer[​](#footer "Direct link to Footer") * Order count with sync button (). **Long press** for Clear and Refresh option ## Key Features[​](#key-features "Direct link to Key Features") ### Order Lookup[​](#order-lookup "Direct link to Order Lookup") Quickly find orders using: * **Order number search** * **Customer name search** * **Date range filtering** * **Status filtering** * **Cashier filtering** ### Receipt Reprinting[​](#receipt-reprinting "Direct link to Receipt Reprinting") For any order, you can: 1. Click the three-dot menu 2. Select the receipt option 3. View, print, or email the receipt ### Order Details[​](#order-details "Direct link to Order Details") Click an order to view: * Complete line item details * Customer information * Payment details * Order notes * Meta data ## Display Settings[​](#display-settings "Direct link to Display Settings") Click the sliders icon () to customise visible columns. ![Orders Settings](/img/orders-page-settings.png) Orders Display Settings ### Available Columns[​](#available-columns "Direct link to Available Columns") #### Essential columns[​](#essential-columns "Direct link to Essential columns") The core columns most stores keep visible — they identify the order and let you act on it. | Column | Description | | ---------------- | ------------------------- | | **Status** | Order status icon | | **Order Number** | Unique order ID | | **Customer** | Customer name and details | | **Total** | Order total | | **Receipt** | Quick receipt access | | **Actions** | Edit, view, etc. | #### Optional columns[​](#optional-columns "Direct link to Optional columns") Extra detail you can switch on when you need it — addresses, dates, and order metadata. | Column | Description | | -------------------- | -------------------------------- | | **Billing Address** | Billing information | | **Shipping Address** | Shipping information | | **Customer Note** | Notes from customer | | **Date Created** | When order was placed | | **Date Modified** | Last modification | | **Date Completed** | When order completed | | **Date Paid** | When payment received | | **Created Via** | Order source (POS, Online, etc.) | | **Cashier** | Who processed the order | | **Payment Method** | Payment type used | ## Order Actions[​](#order-actions "Direct link to Order Actions") Click the three-dot menu (⋮) for options: * **View** - See full order details * **Edit** - Modify order information * **Receipt** - View/print/email receipt * **Sync** - Refresh order from server ### Editing Orders[​](#editing-orders "Direct link to Editing Orders") Select **Edit** from the three-dot menu to modify an existing order. This reopens the order in the cart, where you can: * Add or remove line items * Change quantities or prices * Update the customer * Add notes or metadata After making changes, proceed through checkout again to save the updated order. ### Order Statuses[​](#order-statuses "Direct link to Order Statuses") POS orders use standard WooCommerce order statuses plus one custom status: Typical order flow An order generally progresses **POS - Open → Pending → Processing → Completed**, with **Cancelled** or **Refunded** as end states. Most POS orders skip straight to **Completed** because payment is collected at the point of sale. | Status | Description | | -------------- | ------------------------------------------------------------------- | | **POS - Open** | Order saved from the POS but not yet completed (parked/held orders) | | **Pending** | Awaiting payment | | **Processing** | Payment received, order is being fulfilled | | **Completed** | Order fulfilled and complete | | **Cancelled** | Order was cancelled | | **Refunded** | Order was fully refunded | Most POS orders go directly to **Completed** since payment is collected at the point of sale. Open orders (saved with the **Save to Server** button in the cart) use the **POS - Open** status and can be reopened later to continue the transaction. ### Refunds[​](#refunds "Direct link to Refunds") You can issue full or partial refunds directly from the POS — either back to the original payment method (when the gateway supports it) or as cash from the till. Open the three‑dot menu (⋮) on an order and choose **Refund**, or click the **Refund** button in the order view footer. See [Refunds](/orders/refunds.md) for the full walkthrough, including refund destinations, partial refunds, and how refunds appear on receipts. ## Use Cases[​](#use-cases "Direct link to Use Cases") #### Customer Service * Look up past orders to assist with returns or inquiries * Verify what a customer purchased * Reprint receipts on request #### End of Day * Review all orders for the day * Filter by cashier to verify individual totals * Cross-reference with [Reports](/reports/.md) for reconciliation #### Order Tracking * Monitor order statuses * Track which orders are pending vs completed * Identify orders that need attention ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [ReportsSales reports and reconciliation](/reports/.md) [ReceiptsReceipt customisation](/receipts/at-checkout.md) --- # Refunds Pro Feature Issuing refunds from the POS requires [WCPOS Pro](/getting-started/pro-license.md). Without Pro, you can still process refunds from `WP Admin → WooCommerce → Orders` using WooCommerce's built‑in refund interface. WCPOS lets you refund a WooCommerce order without leaving the register. You can issue a full or partial refund, send the funds back to the original payment method (when the gateway supports it), or record a cash refund from the till — and the refund is tagged with the cashier and store that processed it for reporting. ## Starting a Refund[​](#starting-a-refund "Direct link to Starting a Refund") There are two ways to open the refund form: 1. **From the Orders list** — find the order, click the three‑dot menu () in the actions column, and select **Refund**. 2. **From the order view modal** — open the order, then click the **Refund** button in the footer next to **Print Receipt** and **Cancel**. Both routes open the same **Refund Order #{number}** modal. ### When the Refund Action Appears[​](#when-the-refund-action-appears "Direct link to When the Refund Action Appears") **Refund** is only offered for orders with the following statuses: * **Completed** * **Processing** * **On hold** It does **not** appear on `Pending`, `Cancelled`, `Failed`, `POS – Open`, or already fully‑`Refunded` orders. To refund an already fully‑refunded order, or to refund an order in a status not listed above, use `WP Admin → WooCommerce → Orders`. ## The Refund Form[​](#the-refund-form "Direct link to The Refund Form") At the top of the modal you'll see two figures: * **Total** — the order total. * **Previously Refunded** — the sum of any refunds already issued against this order (shown as a negative amount). Only appears when there is at least one prior refund. Below that is the line items table: | Column | What it shows | | ----------------- | ----------------------------------------------------------------------------------- | | **Product** | The line item name | | **Price** | Unit price (tax‑inclusive or tax‑exclusive, depending on your store setting) | | **Qty** | The remaining refundable quantity (purchased qty minus any previously refunded qty) | | **Refund Qty** | Editable — how many units of this line you want to refund now | | **Refund Amount** | Auto‑calculated from Refund Qty × unit price, including the line's prorated tax | Below the table: * **Custom Amount** — an optional extra amount to add to the refund (for example, refunding a fee that isn't tied to a specific line item). Leave it blank if you don't need it. * **Reason** — an optional note that's saved on the refund record and appears in WooCommerce's order notes. * **Refund destination** — a radio group (see below). * **Refund Total** — the grand total of the refund, recalculated live as you type. ### Refunding Whole vs. Partial Quantities[​](#refunding-whole-vs-partial-quantities "Direct link to Refunding Whole vs. Partial Quantities") There's no separate "full refund" mode — set the Refund Qty for every line to its full remaining quantity to refund the whole order, or set it on just one or two lines for a partial refund. The **Process Refund** button is disabled until **Refund Total** is greater than zero and within the remaining refundable amount. ## Refund Destination[​](#refund-destination "Direct link to Refund Destination") For orders paid with anything other than the built‑in **POS Cash** gateway, the form asks where the refund should go: * **Refund to *(gateway name)*** — the gateway processes the refund through its own provider API. For Stripe Terminal this returns the funds to the original card; for Vipps MobilePay it issues a Vipps refund; and so on. This option only appears for gateways that advertise refund support to the POS — if your gateway doesn't, the option is disabled with the message *"Original payment method refunds are unavailable for this order."* * **Refund via cash** — record the refund as cash returned from the till, regardless of how the order was originally paid. The cashier physically hands the money over; WooCommerce records the refund but does not call any gateway. For orders paid with **POS Cash**, the radio group is hidden — cash is the only sensible destination, so it's used automatically. If WCPOS can't reach the gateway to check refund support, you'll see *"Couldn't verify original payment method refunds. Cash refunds are still available."* — you can still issue a cash refund. ### When to Use Cash vs. Original Method[​](#when-to-use-cash-vs-original-method "Direct link to When to Use Cash vs. Original Method") | Situation | Recommended destination | | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | Card payment via Stripe Terminal / Vipps / etc., customer present and wants the money back on their card | **Refund to *(gateway)*** | | Card payment but customer prefers cash back (and you're allowed to do that) | **Refund via cash** | | Cash sale | **Refund via cash** (automatic; no choice shown) | | Manual card terminal (the gateway can't refund automatically) | **Refund via cash**, then refund manually on your standalone terminal | ## Confirming and Submitting[​](#confirming-and-submitting "Direct link to Confirming and Submitting") When you press **Process Refund**, a confirmation dialog asks *"Refund *(amount)* for Order #*(number)*?"*. Confirming triggers the refund: 1. WCPOS sends the refund to your WooCommerce store. 2. For gateway refunds, WooCommerce hands off to the gateway plugin to process the refund against the provider (Stripe, Vipps, etc.). 3. The order is refreshed locally so the new refund appears immediately. 4. A success toast confirms *"Refund of *(amount)* processed"*. If the gateway rejects the refund (declined card, expired authorization, network error, etc.), an error toast shows the gateway's message. The refund won't be recorded in WooCommerce in that case — you can adjust the form and try again, or fall back to a cash refund. ## After the Refund[​](#after-the-refund "Direct link to After the Refund") * **Partial refund** — the order keeps its existing status (Completed, etc.), and the order view modal shows a **Partially refunded** pill plus a `−(amount) refund` line in the hero subtitle. * **Full refund** — WooCommerce sets the order status to **Refunded**. * **Receipts** — when viewing the receipt for a refunded order, switching to **Live** mode shows the refund reflected in the totals (`Refunded -X` and `Net Total Y` rows on detailed receipts). **Fiscal** mode still shows the original payment‑complete snapshot, untouched — that's what fiscal mode is for. * **Cashier and store audit** — every POS refund is tagged with the cashier (`_pos_user`) and store (`_pos_store`) that issued it, so refunds appear under the right cashier and store in reporting. ## Things to Know[​](#things-to-know "Direct link to Things to Know") * **Coupons + refunds:** orders that used a coupon can still be refunded from the POS, but if you need to adjust how the coupon is recalculated against the refund, use `WP Admin → WooCommerce → Orders`. * **Negative quantities are not supported.** Older versions (v0.4.x) let you add a line with a negative quantity to record a return — this no longer works in v1.x. Use the Refund flow instead. * **Refunds require a server connection.** Unlike checkout, you can't queue a refund offline — the gateway and your store both need to be reachable. * **Issuing additional refunds on a fully‑refunded order** must be done from `WP Admin → WooCommerce → Orders`. ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [OrdersFind, filter, and manage your POS orders](/orders/.md) [Payment GatewaysWhich gateways support refunds back to the original method](/payment/.md) [ReceiptsFiscal vs. live receipts on refunded orders](/receipts/at-checkout.md) --- # Payment Methods WCPOS supports multiple payment methods to accommodate different business needs. The checkout uses an iframe/webview to load the WooCommerce Order Pay page, which means any payment gateway that works with WooCommerce can work in the POS. ## Default Payment Methods[​](#default-payment-methods "Direct link to Default Payment Methods") The free version includes two built-in payment gateways: ### Cash[​](#cash "Direct link to Cash") * Enter amount tendered * Automatic change calculation * No additional configuration required ### Card[​](#card "Direct link to Card") * For use with external card terminals * Simply mark the payment as complete after processing on your terminal * No direct integration required ## Additional Payment Gateways (Pro)[​](#additional-payment-gateways-pro "Direct link to Additional Payment Gateways (Pro)") Pro Feature Additional payment gateways require [WCPOS Pro](/getting-started/pro-license.md). With Pro, you can enable additional WooCommerce payment gateways in the POS checkout: * **Stripe Terminal** - Direct integration with Stripe card readers * **SumUp Terminal** - Integration with SumUp card readers * **Any WooCommerce Gateway** - Enable any gateway installed on your store ## Enabling and Disabling Gateways[​](#enabling-and-disabling-gateways "Direct link to Enabling and Disabling Gateways") Payment gateways are managed in the WordPress admin: 1. Go to `WP Admin > POS > Settings > Checkout` 2. You'll see a list of all installed WooCommerce payment gateways 3. Toggle each gateway on or off for the POS independently of your online store 4. Drag to reorder — the first enabled gateway becomes the default at checkout This means a gateway can be active on your website but disabled in the POS, or vice versa. See [Checkout Settings](/settings/wp-admin/checkout.md) for full details. ## Testing Payments[​](#testing-payments "Direct link to Testing Payments") Before going live with a new gateway: 1. **Cash gateway** — always available for testing the checkout flow without real transactions. 2. **Stripe Terminal** — Stripe provides a [simulated reader](https://docs.stripe.com/terminal/testing) for test mode. Enable test mode in your Stripe dashboard first. 3. **Third-party gateways** — check the gateway's own documentation for sandbox/test mode instructions. Most WooCommerce gateways support a test mode toggle. tip If a newly enabled gateway doesn't appear at checkout, try refreshing the POS. Gateway changes in WP Admin take effect on the next page load. ## Common Issues[​](#common-issues "Direct link to Common Issues") ### Gateway Not Appearing at Checkout[​](#gateway-not-appearing-at-checkout "Direct link to Gateway Not Appearing at Checkout") * Confirm the gateway is enabled for POS in `WP Admin > POS > Settings > Checkout`. * Check that the gateway is also enabled in `WP Admin > WooCommerce > Settings > Payments` — a gateway must be active in WooCommerce before it can appear in the POS. * Refresh the POS after making changes. ### Gateway Displays Incorrectly[​](#gateway-displays-incorrectly "Direct link to Gateway Displays Incorrectly") The checkout iframe loads your site's theme styles, which can sometimes interfere. Use the **Checkout Settings** button in the checkout modal to selectively disable styles or scripts. See [Checkout Troubleshooting](/pos/checkout/.md#checkout-settings-troubleshooting) for details. ### Payment Processing Fails[​](#payment-processing-fails "Direct link to Payment Processing Fails") * Check your site's error logs (`WP Admin > POS > Support > Logs`) for gateway-specific errors. * Ensure your SSL certificate is valid — most payment gateways require HTTPS. * If using a staging or local environment, confirm the gateway supports test/sandbox mode. ## Custom Gateways[​](#custom-gateways "Direct link to Custom Gateways") Create your own payment integrations using the [Custom Gateways](/payment/gateways/.md) system. [Gateways7 items](/payment/gateways/.md) --- # Payment Gateways WCPOS supports several custom payment gateways that extend the functionality of your Point of Sale system. These gateways are designed specifically for POS environments and provide seamless integration with various payment methods and services. ## Available Custom Gateways[​](#available-custom-gateways "Direct link to Available Custom Gateways") ### Hardware Terminal Gateways[​](#hardware-terminal-gateways "Direct link to Hardware Terminal Gateways") * **[Stripe Terminal](/payment/gateways/stripe-terminal.md)** - Accept payments using Stripe Terminal hardware readers * **[SumUp Terminal](/payment/gateways/sumup-terminal.md)** - Process payments through SumUp card readers * **[Square Terminal](/payment/gateways/square-terminal.md)** - Collect in-person payments on Square Terminal devices * **[PayPal Reader (Zettle)](/payment/gateways/paypal-reader.md)** - Take in-person card payments on a PayPal Reader (Zettle) terminal ### Mobile Payment Gateways[​](#mobile-payment-gateways "Direct link to Mobile Payment Gateways") * **[Vipps MobilePay](/payment/gateways/vipps-mobilepay.md)** - Accept phone-based payments via QR code or push notification ### Digital Payment Gateways[​](#digital-payment-gateways "Direct link to Digital Payment Gateways") * **[Email Invoice](/payment/gateways/email-invoice.md)** - Send payment invoices to customers via email * **[Web Checkout](/payment/gateways/web-checkout.md)** - Redirect customers to complete payments online ## Creating Your Own Gateway[​](#creating-your-own-gateway "Direct link to Creating Your Own Gateway") If you need a custom payment gateway for your specific requirements, you can use our **[Gateway Template](/reference/gateway-template.md)** to create your own WCPOS payment gateway. ## Installation Overview[​](#installation-overview "Direct link to Installation Overview") All custom gateways follow a similar installation process: 1. **Download** the latest release from the respective GitHub repository 2. **Install** the plugin via `WP Admin > Plugins > Add New > Upload Plugin` 3. **Configure** the gateway settings in `WP Admin > WooCommerce > Settings > Payments` 4. **Enable** the gateway in `WP Admin > POS > Settings > Checkout` ## Requirements[​](#requirements "Direct link to Requirements") WCPOS : Pro version required for POS checkout WordPress : WordPress with WooCommerce installed API Credentials : Appropriate API keys or credentials for the specific payment service ## Support[​](#support "Direct link to Support") For issues with custom gateways, please visit the respective GitHub repository and create an issue with detailed information about your problem. --- # Email Invoice Gateway The Email Invoice gateway allows you to send payment invoices to customers via email directly from WCPOS. This is perfect for situations where customers prefer to pay later or need to complete payment online using your web store's payment methods. ## Features[​](#features "Direct link to Features") #### Email Integration Send invoices directly from the POS interface #### Customer Management Auto-populate email from existing customer data or add new addresses #### Online Payment Customers receive a "Pay for this order" link to complete payment online #### Flexible Workflow Complete orders in-store or allow remote payment completion ## Installation[​](#installation "Direct link to Installation") 1 #### Install Email Invoice Gateway Install from `WP Admin > POS > Settings > Extensions`, or download the latest **plugin zip asset** (not the GitHub source-code zip or tarball) from the [GitHub releases page](https://github.com/wcpos/email-invoice-gateway/releases) and upload it via `Plugins > Add New > Upload Plugin`. 2 #### Enable in WCPOS 1. Go to `WP Admin > POS > Settings > Checkout` 2. Find the **WCPOS Invoice Payment Gateway** in the list 3. Enable the gateway for use in the POS 4. Save your settings note This gateway doesn't require additional API keys or external service configuration. It uses your existing WordPress email system and WooCommerce payment methods. ## Usage[​](#usage "Direct link to Usage") ### Sending Invoices[​](#sending-invoices "Direct link to Sending Invoices") 1. **Add Items**: Add products to your cart in the POS 2. **Select Gateway**: Choose "Email Invoice" as the payment method 3. **Email Address**: * For existing customers: Email is automatically populated from customer data * For guest orders: Enter the customer's email address manually 4. **Optional**: Check "Save to billing address" to update the customer's billing information 5. **Send Invoice**: Complete the process to send the invoice email ### Customer Experience[​](#customer-experience "Direct link to Customer Experience") When you send an invoice, the customer receives an email containing: * **Order Details**: Complete breakdown of items, quantities, and prices * **Order Total**: Final amount due including taxes and fees * **Payment Link**: Direct link to complete payment online * **Order Information**: Order number and reference details ### Payment Completion[​](#payment-completion "Direct link to Payment Completion") Customers can complete payment in two ways: 1. **Online Payment**: Click the "Pay for this order" link in the email 2. **In-Store Return**: Return to complete payment using other POS payment methods The "Pay for this order" link takes customers to a dedicated payment page on your website where they can use any of your enabled web payment gateways (Stripe, PayPal, etc.). ## Email Management[​](#email-management "Direct link to Email Management") ### Existing Customers[​](#existing-customers "Direct link to Existing Customers") * Email addresses are automatically retrieved from customer profiles * Customer billing information is preserved * Order history is maintained under the customer account ### Guest Customers[​](#guest-customers "Direct link to Guest Customers") * Manually enter email addresses for one-time customers * Option to save email to billing address for future reference * Guest orders are properly tracked in WooCommerce ### Email Templates[​](#email-templates "Direct link to Email Templates") The gateway uses WooCommerce's standard email templates: * **Customisable**: Modify email appearance through WooCommerce email settings * **Branded**: Include your store logo and branding * **Professional**: Clean, professional invoice format * **Mobile-Friendly**: Responsive design for all devices ## Use Cases[​](#use-cases "Direct link to Use Cases") ### Perfect For[​](#perfect-for "Direct link to Perfect For") * **B2B Sales**: Business customers who need to process payments through their accounting systems * **Large Orders**: High-value transactions that require approval or processing time * **Remote Customers**: Customers who need to complete payment after leaving the store * **Account Customers**: Regular customers with established payment terms * **Quote-to-Order**: Converting quotes or estimates into payable invoices ### Workflow Examples[​](#workflow-examples "Direct link to Workflow Examples") #### Retail Store 1. Customer selects items but needs to get approval for purchase 2. Send invoice email with all details 3. Customer completes payment online when ready 4. Order automatically updates in your system #### Service Business 1. Complete service work and add items to POS 2. Send invoice to customer's accounting department 3. Customer pays online using preferred payment method 4. Receive payment confirmation and complete order ## Requirements[​](#requirements "Direct link to Requirements") WCPOS : Pro version required for POS checkout Email System : Working WordPress email configuration Web Payment Gateways : At least one online payment method enabled in WooCommerce SSL Certificate : HTTPS required for secure payment processing ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Common Issues[​](#common-issues "Direct link to Common Issues") Emails not sending * Check WordPress email configuration * Verify SMTP settings if using custom email service * Test with WordPress email testing plugins * Check spam folders for test emails Payment links not working * Ensure WooCommerce is properly configured * Verify at least one payment gateway is enabled for web checkout * Check that SSL certificate is properly installed * Confirm order status allows payment Customer can't complete payment * Verify web payment gateways are active and configured * Check that the order hasn't expired or been cancelled * Ensure customer has sufficient payment method limits * Test the payment process yourself ### Email Delivery[​](#email-delivery "Direct link to Email Delivery") For reliable email delivery, consider: * **SMTP Service**: Use services like SendGrid, Mailgun, or Amazon SES * **Email Plugins**: Install WordPress SMTP plugins for better delivery * **Domain Authentication**: Set up SPF, DKIM, and DMARC records * **Monitoring**: Track email delivery and open rates ### Getting Help[​](#getting-help "Direct link to Getting Help") For technical support: * Visit the [GitHub repository](https://github.com/wcpos/email-invoice-gateway) to report issues * Check WooCommerce email documentation for template customisation * Test email functionality with WordPress email testing tools ## Screenshots[​](#screenshots "Direct link to Screenshots") Screenshots will be added in a future update to show: * Email address entry interface in the POS * Professional invoice email template with order details * Customer payment completion on the web store --- # PayPal Reader (Zettle) Gateway The PayPal Reader gateway lets you accept in-person card payments using a **PayPal Reader (Zettle)** card terminal directly from WCPOS. The browser streams the live payment status from the reader over a secure connection to Zettle's Reader Connect API, so the cashier sees each step of the payment as it happens. ## Features[​](#features "Direct link to Features") #### In-person card payments Take chip, contactless, and mobile-wallet payments on a PayPal Reader (Zettle) terminal #### Live payment status The POS shows real-time progress — connecting, payment in progress, completed, or cancelled #### Amount verified server-side The reported amount is always checked against the order total before the order is placed #### Simple pairing Link a reader from the gateway settings using a pairing code shown on the device ## Requirements[​](#requirements "Direct link to Requirements") WCPOS : Pro version required for POS checkout WordPress : WordPress 5.2+ with WooCommerce active PHP : PHP 7.4 or higher Zettle account : A Zettle developer merchant account, plus a Zettle Client ID and Assertion (JWT) from the Zettle Developer Portal Compatible hardware : A PayPal Reader (Zettle) card terminal Stable connection : Live payments stream status to the reader over the network and require an internet connection Supported hardware and regions PayPal Reader / Zettle availability, supported reader models, and supported countries are determined by your **Zettle merchant account**, not by WCPOS. Confirm your reader and region are supported with PayPal/Zettle before purchasing. ## Installation[​](#installation "Direct link to Installation") 1 #### Install PayPal Reader for WooCommerce Install from `WP Admin > POS > Settings > Extensions`, or download the latest **plugin zip asset** (not the GitHub source-code zip or tarball) from the [GitHub releases page](https://github.com/wcpos/paypal-reader-for-woocommerce/releases) and upload it via `Plugins > Add New > Upload Plugin`. WooCommerce must be installed and active. 2 #### Configure the gateway 1. Navigate to `WP Admin > WooCommerce > Settings > Payments` 2. Find **PayPal Reader** in the payment methods list and open its settings 3. Leave **Enable Test mode** on while you verify the setup. Use the credentials from your Zettle developer merchant account in test mode; disable it later to take live payments 4. Enter your **Zettle Client ID** — your Zettle OAuth client ID from the Zettle Developer Portal 5. Enter your **Zettle Assertion** — your Zettle OAuth assertion (JWT). This is treated as a secret 6. Optionally set the **Title** and **Description** shown to customers 7. **Save** the settings note The **"Enable PayPal Reader for web checkout"** checkbox is for your online store's checkout only — it is **not required for the POS**. You enable the gateway for the POS in a later step. 3 #### Pair your reader 1. After saving, scroll to the **Paired readers** section at the bottom of the settings screen (it appears once your Client ID and Assertion are saved) 2. On the PayPal Reader device, open **Settings → Link with a developer** to display the pairing code 3. Under **Pair a new reader**, enter the **Pairing code** and optionally a **Reader name** (e.g. "Front counter") 4. Click **Pair reader**. The reader appears in the paired list and is ready to take payments Important A reader must be successfully paired before you can take payments. Use **Unpair** on the paired list to remove a reader. 4 #### Enable in WCPOS 1. Go to `WP Admin > POS > Settings > Checkout` 2. Find the **PayPal Reader** gateway in the list 3. Enable it for use in the POS 4. Save your settings ## Taking a payment[​](#taking-a-payment "Direct link to Taking a payment") 1. **Add items** to the cart in the POS and proceed to checkout 2. **Select PayPal Reader** as the payment method 3. **Choose a paired reader** and start the payment. (If none are paired, you'll be prompted to ask the store admin to pair one in `WooCommerce → Settings → Payments → PayPal Reader`.) 4. The POS shows live status as it connects: *"Connecting to reader…"*, *"Reader ready. Requesting payment…"*, *"Payment in progress…"* 5. The customer taps or inserts their card on the reader 6. On success, the amount is verified against the order total, the transaction reference is recorded, and the order is placed automatically 7. Use **Cancel payment** at any point to cancel the request on the reader ## Going live[​](#going-live "Direct link to Going live") When you've verified everything in test mode: 1. Disable **Enable Test mode** 2. Replace your Zettle test credentials with your **production** Client ID and Assertion 3. Save — the endpoints and flow are identical; only the merchant account differs ## Requirements recap & limitations[​](#limitations "Direct link to Requirements recap & limitations") * **The order is only completed after a confirmed reader result.** WCPOS will not place the order unless the payment reports as completed. * **Amount-mismatch protection.** If the amount the reader reports doesn't match the order total, the payment is refused — so avoid editing the cart total mid-payment. * **Connectivity.** Live payments depend on the browser maintaining a session to Zettle's Reader Connect API; a stable internet connection is required. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") The Paired readers section isn't showing Save your **Zettle Client ID** and **Assertion** first. The pairing panel only appears once both credentials are saved. You'll otherwise see *"Save your Zettle Client ID and Assertion above before pairing a reader."* Reader won't pair * On the reader, make sure you opened **Settings → Link with a developer** to get a fresh pairing code * Enter the code exactly as shown, before it expires * Confirm your Zettle Client ID and Assertion are correct and saved * Ensure the reader and your network have a stable internet connection Payment is refused with an amount mismatch The plugin verifies the reader-reported amount against the order total and refuses any mismatch. Don't change the cart or order total while a payment is in progress — cancel the payment, adjust the cart, then start a new payment. No real payments are processed / an admin warning about a 'mock reader' appears A development/CI constant (`PRWC_USE_MOCK_READER`) is defined in `wp-config.php`. Remove that constant before taking live payments — while it's set, no real payments are processed. ### Getting help[​](#getting-help "Direct link to Getting help") * Report gateway issues on the [GitHub repository](https://github.com/wcpos/paypal-reader-for-woocommerce) * Contact PayPal/Zettle support for account, reader hardware, and regional availability questions --- # Square Terminal Gateway The Square Terminal gateway lets you collect WooCommerce order payments on [Square Terminal](https://squareup.com/hardware/terminal) hardware directly from WCPOS. A payment is requested from WooCommerce and completed on a paired Square Terminal device, and the result is written back to the order. ## Features[​](#features "Direct link to Features") #### Hardware Integration Send payments to paired Square Terminal devices and collect card-present payments #### Easy Pairing Pair terminals from WooCommerce using a short-lived Square Device Code #### Webhook-Confirmed Verified Square webhooks confirm completion, with live status while you wait #### Secure Transactions PCI-compliant, card-present processing handled on Square hardware #### Sandbox & Production Validate against the Square Sandbox before switching to live payments ## How It Works[​](#how-it-works "Direct link to How It Works") Unlike browser-SDK gateways, Square Terminal uses Square's **server-side Terminal API**. When you start a payment, WooCommerce creates a Terminal Checkout for the order and Square pushes it to the paired device. The customer pays on the terminal, and Square notifies your site with a signed webhook. The webhook is the authoritative completion signal; the POS also polls so the status updates while you wait. This means the Square Terminal device must be online and signed in to the same Square account and location, and your site must be publicly reachable over HTTPS so Square can deliver webhooks. ## Installation[​](#installation "Direct link to Installation") 1 #### Install Square Terminal for WooCommerce Install from `WP Admin > POS > Settings > Extensions`, or download the latest **plugin zip asset** (not the GitHub source-code zip or tarball) from the [GitHub releases page](https://github.com/wcpos/square-terminal-for-woocommerce/releases) and upload it via `Plugins > Add New > Upload Plugin`. 2 #### Configure Square Settings 1. Navigate to `WP Admin > WooCommerce > Settings > Payments` 2. Find **Square Terminal** in the payment methods list and click it to open the settings 3. Choose the **Environment** (`Sandbox` for testing, `Production` for live payments) 4. Enter your **Access Token** for the selected environment (Sandbox or Production), available from the [Square Developer Dashboard](https://developer.squareup.com/apps) 5. Enter your **Location ID** — the Square location where Terminal payments are taken 6. Enter your **Webhook Signature Key** and **Webhook Notification URL** (see the next step) 7. Click **Validate Settings** to confirm the credentials work, then save note You do not need to enable the Square Terminal gateway in WooCommerce settings. It will be enabled specifically for the POS in a later step. 3 #### Set Up Webhooks in Square Square sends a signed webhook when a Terminal payment finishes, and this is what marks the order as paid. 1. In the [Square Developer Dashboard](https://developer.squareup.com/apps), open your application and go to the **Webhooks** section 2. Add a subscription for the **`terminal.checkout.updated`** event 3. Set the notification URL to the **Webhook Notification URL** shown in the plugin settings — it must match **exactly** 4. Copy the **Webhook Signature Key** into the plugin settings so incoming events can be verified Important The Webhook Notification URL in Square must exactly match the value in the plugin settings, and the Webhook Signature Key must be correct. If they don't match, Square payments will complete on the device but the WooCommerce order will not update. 4 #### Pair Your Square Terminal 1. On the same settings page, click **Create Device Code** 2. A pairing code is generated and shown to you 3. On your Square Terminal, sign in and enter the code on the device-pairing screen 4. Once paired, the terminal is linked to your configured location. Note its **Device ID** — you'll enter this when taking a payment Important The terminal must be successfully paired and online before you can process payments. Make sure pairing is complete before proceeding. 5 #### Enable in WCPOS 1. Go to `WP Admin > POS > Settings > Checkout` 2. Find the **Square Terminal** gateway in the list 3. Enable the gateway for use in the POS 4. Save your settings ## Usage[​](#usage "Direct link to Usage") ### Processing Payments[​](#processing-payments "Direct link to Processing Payments") 1. **Add Items**: Add products to your cart in the POS 2. **Select Gateway**: Choose "Square Terminal" as the payment method 3. **Choose Device**: Enter the **Terminal Device ID** of the paired terminal that should take the payment 4. **Start Payment**: Click **Start Payment** — Square pushes the checkout to the device 5. **Customer Payment**: The customer taps, inserts, or swipes their card on the Square Terminal 6. **Automatic Completion**: When Square's verified webhook confirms the payment, the order is marked paid. The live status updates while you wait. ### Payment Controls[​](#payment-controls "Direct link to Payment Controls") When using the Square Terminal gateway, you have the following options: * **Start Payment**: Send a new payment request to the selected terminal * **Cancel Payment**: Cancel a payment that is currently in progress on the terminal * **Payment Status**: A live status area shows the current state of the payment * **Payment Log**: A per-order log records each meaningful Square step and outcome ### Order Management[​](#order-management "Direct link to Order Management") * **Webhook-Authoritative Completion**: Orders are marked paid only when a verified Square webhook confirms the Terminal payment * **Payment Tracking**: Square identifiers and a payment log are stored on the order, and key steps are written to order notes * **Receipt Generation**: Standard POS receipts are generated after successful payments ## Requirements[​](#requirements "Direct link to Requirements") Square Account : Active Square seller account API Credentials : Access Token, Location ID, and Webhook Signature Key from the Square Developer Dashboard Compatible Hardware : A Square Terminal device, online and signed in to the same Square location Public HTTPS Site : Your site must be reachable over HTTPS so Square can deliver webhooks WCPOS : Pro version required for POS checkout ## Hardware Compatibility[​](#hardware-compatibility "Direct link to Hardware Compatibility") Connectivity Requirements Square Terminal uses Square's server-side Terminal API: the checkout is created by your site and delivered to the paired device by Square. The terminal must be online and signed in to the same Square account and location, and your site must receive Square webhooks over HTTPS for orders to update. ### Supported Terminals[​](#supported-terminals "Direct link to Supported Terminals") * **Square Terminal** ✅ — Square's dedicated countertop card terminal ## Scope & Limitations[​](#scope-and-limitations "Direct link to Scope & Limitations") v0.1 scope * This early release is focused on **POS / order-pay** flows. Availability on the customer-facing storefront checkout is off by default and must be explicitly enabled. * It **collects payments only** — refunds are not yet supported. Square identifiers are stored on the order so refund support can be added later. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Common Issues[​](#common-issues "Direct link to Common Issues") Device won't pair * Make sure you entered the Device Code before it expired — generate a fresh one with **Create Device Code** if needed * Confirm the terminal is online and signed in to the same Square account and **Location ID** as the plugin * Check that the **Environment** (Sandbox/Production) and **Access Token** match the account the terminal is signed in to Validate Settings fails * Verify the **Access Token** matches the selected **Environment** (a Sandbox token won't work in Production, and vice versa) * Confirm the **Location ID** belongs to that account * Re-copy the token from the Square Developer Dashboard in case of stray characters Payment completes on the terminal but the order doesn't update * The **Webhook Notification URL** in Square must match the plugin setting **exactly** * Make sure the **`terminal.checkout.updated`** event is subscribed in the Square Developer Dashboard * Confirm the **Webhook Signature Key** in the plugin matches the one in Square * Ensure your site is publicly reachable over HTTPS; check webhook delivery attempts in the Square Dashboard Payment won't start * Confirm a valid **Terminal Device ID** is entered and the device is paired and online * Check that the device is signed in to the configured **Location ID** * Review the **Payment Log** and WordPress error logs for Square API messages ### Getting Help[​](#getting-help "Direct link to Getting Help") For technical support: * Visit the [GitHub repository](https://github.com/wcpos/square-terminal-for-woocommerce) to report issues * Check the [Square Terminal API documentation](https://developer.squareup.com/docs/terminal-api/overview) for hardware and API guidance * Contact Square support for account and hardware issues ## Screenshots[​](#screenshots "Direct link to Screenshots") Screenshots will be added in a future update to show: * Square credentials, webhook, and device-pairing configuration * Gateway enablement in WCPOS settings * Payment processing workflow in the POS checkout --- # Stripe Terminal Gateway The Stripe Terminal gateway allows you to accept in-person payments using Stripe Terminal hardware readers directly within WCPOS. This gateway supports both physical card readers and simulator mode for testing. ## Features[​](#features "Direct link to Features") #### Hardware Integration Connect physical Stripe Terminal readers via internet connection #### Simulator Mode Test payments without hardware using Stripe's simulator #### Real-time Processing Instant payment processing and confirmation #### Secure Transactions PCI-compliant payment processing through Stripe #### Phone Orders (MOTO) Accept card payments over the phone by keying details into the reader ## Installation[​](#installation "Direct link to Installation") 1 #### Install Stripe Terminal for WooCommerce Install from `WP Admin > POS > Settings > Extensions`, or download the latest **plugin zip asset** (not the GitHub source-code zip or tarball) from the [GitHub releases page](https://github.com/wcpos/stripe-terminal-for-woocommerce/releases) and upload it via `Plugins > Add New > Upload Plugin`. 2 #### Configure Stripe Settings 1. Navigate to `WP Admin > WooCommerce > Settings > Payments` 2. Find **Stripe Terminal** in the payment methods list 3. Click on **Stripe Terminal** to access settings 4. Enter your **Stripe Secret Key** (you can get this from your Stripe Dashboard) 5. Save the settings note You do not need to enable the Stripe Terminal gateway in WooCommerce settings. It will be enabled specifically for the POS in the next step. 3 #### Enable in WCPOS 1. Go to `WP Admin > POS > Settings > Checkout` 2. Find the **Stripe Terminal** gateway in the list 3. Enable the gateway for use in the POS 4. Save your settings ## Usage[​](#usage "Direct link to Usage") ### Connecting a Reader[​](#connecting-a-reader "Direct link to Connecting a Reader") When you select the Stripe Terminal gateway during checkout in the POS: 1. **Choose Connection Method**: You can either connect a physical reader or use the simulator 2. **Physical Reader**: Follow the on-screen instructions to connect your Stripe Terminal device 3. **Simulator**: Select simulator mode to test various payment scenarios without hardware ### Processing Payments[​](#processing-payments "Direct link to Processing Payments") 1. **Add Items**: Add products to your cart in the POS 2. **Select Gateway**: Choose "Stripe Terminal" as the payment method 3. **Connect Reader**: Connect your reader or choose simulator mode 4. **Process Payment**: Follow the prompts to complete the transaction 5. **Confirmation**: The order will be automatically completed upon successful payment ### Testing with Simulator[​](#testing-with-simulator "Direct link to Testing with Simulator") The simulator allows you to test various payment methods and scenarios: * **Card Payments**: Test different card types (Visa, Mastercard, etc.) * **Contactless Payments**: Simulate tap-to-pay transactions * **Error Scenarios**: Test declined payments and other error conditions * **Different Amounts**: Test various transaction amounts ### Phone Orders (MOTO)[​](#phone-orders-moto "Direct link to Phone Orders (MOTO)") MOTO (Mail Order/Telephone Order) lets you process card payments for customers who aren't physically present — for example, when taking an order over the phone. Instead of tapping or inserting a card, the merchant keys the card details directly into the terminal reader's screen. #### Setup[​](#setup "Direct link to Setup") 1 #### Request MOTO access from Stripe MOTO is not enabled by default. Contact [Stripe support](https://support.stripe.com/contact) and ask them to enable MOTO permissions for your account. This is a quick process but requires manual approval from Stripe. 2 #### Enable in plugin settings 1. Navigate to `WP Admin > WooCommerce > Settings > Payments > Stripe Terminal` 2. Check the **Phone Orders (MOTO)** checkbox 3. Save the settings 3 #### Connect a compatible reader MOTO only works with compatible internet-connected readers listed in [Supported Terminals](#supported-terminals-internet-connected). The toggle will not appear for other reader types. #### Taking a Phone Order[​](#taking-a-phone-order "Direct link to Taking a Phone Order") 1. Connect a compatible reader (see [Supported Terminals](#supported-terminals-internet-connected)) 2. At the payment screen, toggle **Phone Order** on 3. Click **Collect Card Payment** — the reader will display a card number entry screen instead of prompting for a tap/insert 4. Key in the customer's card number, expiry, and CVV on the reader 5. The payment processes as normal from there tip MOTO payments use `card` as the payment method type rather than `card_present`. This means they are treated more like online transactions from Stripe's perspective, so standard online card processing fees apply rather than in-person rates. caution The Phone Order toggle only appears when all three conditions are met: the MOTO setting is enabled in plugin settings, a compatible reader is connected, and the reader is not a simulator. If you don't see the toggle, check these conditions. ## Requirements[​](#requirements "Direct link to Requirements") Stripe Account : Active Stripe account with Terminal enabled API Keys : Stripe secret key from your dashboard WCPOS : Pro version required for POS checkout HTTPS : Your site must use SSL/HTTPS for security ## Hardware Compatibility[​](#hardware-compatibility "Direct link to Hardware Compatibility") Connectivity Requirements This implementation uses Stripe's JavaScript SDK, which means it works through web applications but requires **internet-connected terminals only**. Bluetooth terminals are not currently supported. ### Supported Terminals (Internet-Connected)[​](#supported-terminals-internet-connected "Direct link to Supported Terminals (Internet-Connected)") * **Stripe Reader S700/S710** ✅ - Ethernet/WiFi-connected terminal * **WisePOS E** ✅ - WiFi-connected terminal ### Unsupported Terminals (Bluetooth)[​](#unsupported-terminals-bluetooth "Direct link to Unsupported Terminals (Bluetooth)") * **BBPOS Chipper 2X BT** ❌ - Bluetooth only * **BBPOS WisePad 3** ❌ - Bluetooth only * **Verifone P400** ❌ - Bluetooth only Future Support Bluetooth terminal support is planned for a future iOS and Android app release. When available, this will enable support for all Stripe Terminal certified readers including the M2 and WisePad 3. ### Common Issues[​](#common-issues "Direct link to Common Issues") Reader won't connect * Ensure you're using a [supported internet-connected terminal](#supported-terminals-internet-connected) * Verify the terminal is connected to WiFi/Ethernet and online * Check that your Stripe account has Terminal enabled * Confirm the terminal is registered in your Stripe Dashboard Payment declined * Check that your Stripe account is active and in good standing * Verify the card being used is valid * Ensure sufficient funds are available Phone Order toggle not showing * Verify the **Phone Orders (MOTO)** setting is enabled in `WooCommerce > Settings > Payments > Stripe Terminal` * Make sure you're connected to a compatible reader (see [Supported Terminals](#supported-terminals-internet-connected)) — the toggle is hidden for other reader types * The toggle does not appear when using the simulator MOTO payment fails with an error * Confirm that Stripe has enabled MOTO permissions on your account — contact [Stripe support](https://support.stripe.com/contact) if you haven't already * Double-check that the card details were entered correctly on the reader * MOTO payments may have stricter fraud checks — ensure the card is valid and has sufficient funds SSL certificate errors * Stripe Terminal requires HTTPS - ensure your site has a valid SSL certificate * Check that your SSL certificate is properly configured ### Getting Help[​](#getting-help "Direct link to Getting Help") For technical support: * Visit the [GitHub repository](https://github.com/wcpos/stripe-terminal-for-woocommerce) to report issues * Check the [Stripe Terminal documentation](https://stripe.com/docs/terminal) for hardware-specific guidance * Contact Stripe support for account-related issues ## Screenshots[​](#screenshots "Direct link to Screenshots") Screenshots will be added in a future update to show: * Gateway configuration in WooCommerce payment settings * POS checkout interface with Stripe Terminal selection * Simulator testing interface with various payment methods --- # SumUp Terminal Gateway The SumUp Terminal gateway enables you to accept card payments using SumUp card readers directly within WCPOS. This gateway provides seamless integration with SumUp's payment processing system for in-person transactions. ## Features[​](#features "Direct link to Features") #### Hardware Integration Connect SumUp card readers to your POS system via internet connection #### Real-time Processing Instant payment processing and order completion #### Secure Transactions PCI-compliant payment processing through SumUp #### Easy Pairing Simple device pairing process with pairing codes ## Installation[​](#installation "Direct link to Installation") 1 #### Install SumUp Terminal for WooCommerce Install from `WP Admin > POS > Settings > Extensions`, or download the latest **plugin zip asset** (not the GitHub source-code zip or tarball) from the [GitHub releases page](https://github.com/wcpos/sumup-terminal-for-woocommerce/releases) and upload it via `Plugins > Add New > Upload Plugin`. 2 #### Configure SumUp Settings 1. Navigate to `WP Admin > WooCommerce > Settings > Payments` 2. Find **SumUp Terminal** in the payment methods list 3. Click on **SumUp Terminal** to access settings 4. Enter your **SumUp API Key** (available from your SumUp merchant dashboard) 5. Save the settings note You do not need to enable the SumUp Terminal gateway in WooCommerce settings. It will be enabled specifically for the POS in a later step. 3 #### Pair Your SumUp Terminal 1. On the same settings page, locate the **Pair Reader** section 2. On your SumUp device, navigate to the pairing screen to display the pairing code 3. Enter the pairing code displayed on your SumUp device 4. Click **"Pair Reader"** to establish the connection 5. Wait for confirmation that the reader has been successfully paired Important The reader must be successfully paired before you can process payments. Ensure the pairing process is completed before proceeding. 4 #### Enable in WCPOS 1. Go to `WP Admin > POS > Settings > Checkout` 2. Find the **SumUp Terminal** gateway in the list 3. Enable the gateway for use in the POS 4. Save your settings ## Usage[​](#usage "Direct link to Usage") ### Processing Payments[​](#processing-payments "Direct link to Processing Payments") 1. **Add Items**: Add products to your cart in the POS 2. **Select Gateway**: Choose "SumUp Terminal" as the payment method 3. **Start Payment**: Click to initiate a new payment on your SumUp device 4. **Customer Payment**: Customer completes payment on the SumUp terminal 5. **Automatic Completion**: The order automatically completes when payment is detected ### Payment Controls[​](#payment-controls "Direct link to Payment Controls") When using the SumUp Terminal gateway, you have the following options: * **Start New Payment**: Initiate a payment request on the connected terminal * **Cancel Payment**: Cancel a payment currently in process * **Payment Status**: Monitor the current status of the payment process ### Order Management[​](#order-management "Direct link to Order Management") * **Automatic Updates**: Orders are automatically marked as completed upon successful payment * **Payment Tracking**: All payment details are recorded in the order notes * **Receipt Generation**: Standard POS receipts are generated after successful payments ## Requirements[​](#requirements "Direct link to Requirements") SumUp Account : Active SumUp merchant account API Access : SumUp API key from your merchant dashboard Compatible Hardware : SumUp card reader device WCPOS : Pro version required for POS checkout Stable Connection : Reliable internet connection for API communication ## Hardware Compatibility[​](#hardware-compatibility "Direct link to Hardware Compatibility") Connectivity Requirements This implementation uses SumUp's JavaScript SDK, which means it works through web applications but requires **internet-connected terminals only**. Bluetooth terminals are not currently supported. ### Supported Terminals (Internet-Connected)[​](#supported-terminals-internet-connected "Direct link to Supported Terminals (Internet-Connected)") * **SumUp Solo** ✅ - WiFi/Ethernet connected terminal ### Unsupported Terminals (Bluetooth)[​](#unsupported-terminals-bluetooth "Direct link to Unsupported Terminals (Bluetooth)") * **SumUp Air** ❌ - Bluetooth only * **SumUp 3G** ❌ - Bluetooth only Future Support Bluetooth terminal support is planned for a future iOS and Android app release. When available, this will enable support for all SumUp certified terminals including the Air and 3G models. ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Common Issues[​](#common-issues "Direct link to Common Issues") Reader won't pair * Ensure you're using a supported internet-connected terminal (Solo only) * Verify your SumUp Solo device is connected to WiFi and online * Check that the device is in pairing mode and pairing code is entered correctly * Confirm your SumUp account has API access enabled * Ensure stable internet connection during pairing Payment not processing * Verify the reader is properly paired * Check that your SumUp account is active and in good standing * Ensure the device has sufficient battery and connectivity * Confirm API key is correct and active Order not completing * Check internet connection stability * Verify webhook settings in your SumUp account * Ensure the payment was successful on the SumUp terminal * Check WordPress error logs for API communication issues ### API Rate Limits[​](#api-rate-limits "Direct link to API Rate Limits") The gateway is optimized to reduce API calls and avoid rate limiting: * Payment status is checked efficiently * Unnecessary API requests are minimized * Automatic retry logic handles temporary failures ### Getting Help[​](#getting-help "Direct link to Getting Help") For technical support: * Visit the [GitHub repository](https://github.com/wcpos/sumup-terminal-for-woocommerce) to report issues * Check the [SumUp developer documentation](https://developer.sumup.com/) for API-related questions * Contact SumUp support for account and hardware issues ## Screenshots[​](#screenshots "Direct link to Screenshots") Screenshots will be added in a future update to show: * SumUp API key configuration and device pairing interface * Gateway enablement in WCPOS settings * Payment processing workflow in the POS checkout --- # Vipps MobilePay Gateway The Vipps MobilePay gateway lets you accept phone-based payments directly within WCPOS. Customers pay by scanning a QR code on screen or confirming a push notification on their phone — no card reader hardware needed. ## Features[​](#features "Direct link to Features") #### QR Code Payments Display a QR code at checkout for customers to scan and pay with their phone #### Push Notifications Send a payment request straight to the customer's phone by entering their number #### Nordic Coverage Works with Vipps in Norway, MobilePay in Denmark and Finland #### Auto Capture Capture funds immediately after authorization, or reserve for manual capture ## Installation[​](#installation "Direct link to Installation") 1 #### Install WCPOS Vipps MobilePay Install from `WP Admin > POS > Settings > Extensions`, or download the latest **plugin zip asset** (not the GitHub source-code zip or tarball) from the [GitHub releases page](https://github.com/wcpos/wcpos-vipps/releases) and upload it via `Plugins > Add New > Upload Plugin`. 2 #### Configure Vipps Credentials 1. Navigate to `WP Admin > WooCommerce > Settings > Payments` 2. Find **WCPOS Vipps MobilePay** in the payment methods list 3. Click on **WCPOS Vipps MobilePay** to access settings 4. Enter your credentials from the [Vipps Portal](https://portal.vipps.no/): * **Merchant Serial Number (MSN)** * **Client ID** * **Client Secret** * **Subscription Key** 5. Save the settings note You don't need to enable the gateway here for POS use — it will be enabled specifically for the POS in the next step. Enabling it in WooCommerce settings would also make it available on your online store checkout, which can be useful for testing. Already using the Vipps plugin? If you have the official [Checkout with Vipps MobilePay](https://wordpress.org/plugins/woo-vipps/) plugin installed, your credentials will be imported automatically when you activate this plugin. You can skip the manual credential entry. 3 #### Enable in WCPOS 1. Go to `WP Admin > POS > Settings > Checkout` 2. Find the **WCPOS Vipps MobilePay** gateway in the list 3. Enable the gateway for use in the POS 4. Save your settings ## Usage[​](#usage "Direct link to Usage") ### Processing Payments — QR Code[​](#processing-payments--qr-code "Direct link to Processing Payments — QR Code") 1. **Add Items**: Add products to your cart in the POS 2. **Select Gateway**: Choose "Vipps MobilePay" as the payment method 3. **Generate QR Code**: Click the "Generate QR Code" button 4. **Customer Scans**: The customer scans the QR code with their Vipps or MobilePay app 5. **Customer Confirms**: The customer confirms payment in their app 6. **Automatic Completion**: The order completes automatically once payment is authorized ### Processing Payments — Send to Phone[​](#processing-payments--send-to-phone "Direct link to Processing Payments — Send to Phone") 1. **Add Items**: Add products to your cart in the POS 2. **Select Gateway**: Choose "Vipps MobilePay" as the payment method 3. **Enter Phone Number**: Type the customer's phone number 4. **Send to Phone**: Click the "Send to Phone" button 5. **Customer Confirms**: The customer receives a push notification or is directed to the Vipps landing page, then confirms payment in their app 6. **Automatic Completion**: The order completes automatically once payment is authorized The plugin automatically detects the best method for sending the payment request to the customer's phone: * **Direct push** (preferred) — Sends a notification straight to the customer's Vipps app. This is the fastest experience but requires Vipps to enable `PUSH_MESSAGE` on your sales unit (see [Enabling Direct Push](#enabling-direct-push) below). * **Landing page fallback** — If direct push isn't enabled, the plugin opens the Vipps landing page in a new browser tab. The landing page handles sending the notification. This works immediately with no special approval. The first time the plugin detects that direct push isn't available, you'll see a brief message asking you to click "Send to Phone" again. After that, it remembers the result and works seamlessly. ### Enabling Direct Push[​](#enabling-direct-push "Direct link to Enabling Direct Push") The direct push flow provides the best experience for phone payments — no extra tabs, no landing pages. To enable it: 1. Log in to [portal.vippsmobilepay.com](https://portal.vippsmobilepay.com) 2. Contact your Vipps key account manager, partner manager, or customer service 3. Tell them: **"I need PUSH\_MESSAGE enabled on my MSN for use with a POS integration"** Once approved, the plugin detects the change automatically within 24 hours and switches to the direct push flow. You'll see a reminder notice on the gateway settings page while you're using the landing page fallback. ### Cancelling a Payment[​](#cancelling-a-payment "Direct link to Cancelling a Payment") While waiting for the customer to confirm, you can click the **Cancel Payment** button to abort the transaction. This cancels the pending payment on the Vipps side and resets the checkout interface. ### Refunds[​](#refunds "Direct link to Refunds") Refunds are handled through the standard WooCommerce refund process. Open the order, click **Refund**, enter the amount, and the refund is processed through the Vipps API automatically. ## Supported Markets[​](#supported-markets "Direct link to Supported Markets") Vipps MobilePay operates across the Nordic region under two brands: | Region | Brand | Currencies | | ---------------- | --------- | ---------- | | Norway | Vipps | NOK | | Denmark, Finland | MobilePay | DKK, EUR | Your merchant account determines which markets and currencies are available. Customers in any supported market can pay using their local Vipps or MobilePay app. ## Requirements[​](#requirements "Direct link to Requirements") Vipps Account : Active Vipps MobilePay merchant account with API credentials API Credentials : Merchant Serial Number, Client ID, Client Secret, and Subscription Key WCPOS : Pro version required for POS checkout. The gateway also works on the standard WooCommerce web checkout without Pro. HTTPS : Your site must use SSL/HTTPS (required by the Vipps API) ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Common Issues[​](#common-issues "Direct link to Common Issues") Payment not completing * The checkout polls for up to 5 minutes — if the customer doesn't confirm within that window, the payment times out * Check that you're not mixing up test mode and production credentials * Verify your internet connection is stable on both the POS device and the customer's phone Invalid credentials error * Double-check all four credential fields (MSN, Client ID, Client Secret, Subscription Key) * Make sure you're using test credentials when test mode is enabled, and production credentials when it's disabled * Verify your credentials in the [Vipps Portal](https://portal.vipps.no/) 'Send to Phone' opens a new tab instead of sending directly This means your Vipps account doesn't have `PUSH_MESSAGE` enabled yet. The plugin is using the landing page fallback, which works but adds an extra step. To get the smoother direct push experience, contact Vipps and ask them to enable PUSH\_MESSAGE on your sales unit (MSN). See [Enabling Direct Push](#enabling-direct-push) above. QR code not generating * Confirm your site is running over HTTPS — the Vipps API rejects requests from HTTP sites * Check the WooCommerce logs (`WooCommerce > Status > Logs`) for API error details * Verify your merchant account is active and has the ePayment API enabled ### Getting Help[​](#getting-help "Direct link to Getting Help") For technical support: * Visit the [GitHub repository](https://github.com/wcpos/wcpos-vipps) to report issues * Check the [Vipps developer documentation](https://developer.vippsmobilepay.com/) for API-related questions * Contact Vipps MobilePay support for account and credential issues ## Screenshots[​](#screenshots "Direct link to Screenshots") Screenshots will be added in a future update to show: * Gateway configuration in WooCommerce payment settings * POS checkout interface with QR code and push notification options * Payment confirmation flow --- # Web Checkout Gateway The Web Checkout gateway allows customers to complete their POS transactions using your web store's checkout system. This gateway creates a seamless bridge between your in-store POS and online payment methods, perfect for situations where customers prefer to pay using their own devices or when you need access to web-only payment methods. ## Features[​](#features "Direct link to Features") #### Seamless Integration Direct link from POS to web checkout #### All Payment Methods Access to all your web store's enabled payment gateways #### Customer Control Customers can pay using their own devices and preferred methods #### Order Synchronisation Automatic order updates between POS and web store ## Installation[​](#installation "Direct link to Installation") 1 #### Download and Install 1. Visit the [Web Checkout Gateway releases page](https://github.com/wcpos/web-checkout-gateway/releases) 2. Download the latest **woocommerce-pos-web-checkout-gateway.zip** file 3. In your WordPress admin, go to `Plugins > Add New > Upload Plugin` 4. Upload the zip file and activate the plugin 2 #### Enable in WCPOS 1. Go to `WP Admin > POS > Settings > Checkout` 2. Find the **WCPOS Web Checkout Gateway** in the list 3. Enable the gateway for use in the POS 4. Save your settings note This gateway leverages your existing WooCommerce payment methods, so ensure you have at least one web payment gateway properly configured (Stripe, PayPal, etc.). ## Usage[​](#usage "Direct link to Usage") ### Initiating Web Checkout[​](#initiating-web-checkout "Direct link to Initiating Web Checkout") 1. **Add Items**: Add products to your cart in the POS 2. **Select Gateway**: Choose "Web Checkout" as the payment method 3. **Generate Link**: The system creates a unique checkout link for the order 4. **Customer Access**: Customer clicks the link to access the web checkout 5. **Online Payment**: Customer completes payment using web store payment methods ### Payment Process[​](#payment-process "Direct link to Payment Process") The Web Checkout gateway follows this workflow: 1. **Order Creation**: POS creates a pending order in WooCommerce 2. **Checkout Link**: System generates a secure, unique payment link 3. **Customer Redirect**: Customer is directed to the web checkout page 4. **Payment Selection**: Customer chooses from available web payment methods 5. **Payment Processing**: Standard WooCommerce checkout process handles payment 6. **Order Completion**: Order status updates automatically upon successful payment ### POS Workflow[​](#pos-workflow "Direct link to POS Workflow") After initiating web checkout: 1. **Monitor Status**: Keep the POS order screen open to monitor payment status 2. **Customer Payment**: Customer completes payment on their device or your tablet 3. **Automatic Update**: Order status updates in real-time when payment is received 4. **Process Payment**: Click "Process Payment" button in POS to continue to receipt 5. **Receipt Generation**: Generate and print receipt as normal ## Use Cases[​](#use-cases "Direct link to Use Cases") ### Perfect For[​](#perfect-for "Direct link to Perfect For") * **Customer Preference**: Customers who prefer to use their own payment apps or cards * **Complex Payments**: Transactions requiring payment methods not available in POS * **Split Payments**: Customers wanting to use multiple payment methods * **Loyalty Programs**: Access to web-based loyalty point redemption * **Gift Cards**: Customers with digital gift cards or store credit * **International Cards**: Payment methods that work better through web gateways ### Workflow Examples[​](#workflow-examples "Direct link to Workflow Examples") #### Retail Store 1. Customer shops in-store and brings items to checkout 2. Customer prefers to pay with their mobile wallet app 3. Staff selects Web Checkout gateway 4. Customer scans QR code or clicks link on their phone 5. Customer completes payment using preferred method 6. Staff processes receipt and completes transaction #### Service Business 1. Complete service and add charges to POS 2. Customer wants to pay with business credit card 3. Generate web checkout link 4. Customer enters payment details on secure web form 5. Payment processes through your web gateway 6. Order completes and receipt is generated ## Technical Details[​](#technical-details "Direct link to Technical Details") ### Order Management[​](#order-management "Direct link to Order Management") * **Pending Orders**: Orders are created with "pending payment" status * **Status Updates**: Automatic status changes when payment is received * **Order Notes**: Payment details are recorded in order notes * **Inventory**: Stock is reserved during the checkout process ### Security[​](#security "Direct link to Security") * **Unique Links**: Each checkout session has a unique, time-limited URL * **SSL Required**: All payment processing occurs over secure HTTPS connections * **PCI Compliance**: Leverages your existing PCI-compliant web payment gateways * **Session Management**: Secure session handling prevents unauthorized access ### Payment Methods[​](#payment-methods "Direct link to Payment Methods") The gateway provides access to all your configured WooCommerce payment methods: * **Credit/Debit Cards**: Stripe, Square, Authorize.net, etc. * **Digital Wallets**: PayPal, Apple Pay, Google Pay * **Bank Transfers**: Direct bank payment methods * **Buy Now, Pay Later**: Klarna, Afterpay, Sezzle * **Cryptocurrency**: Bitcoin and other crypto payment gateways * **Local Methods**: Region-specific payment methods ## Requirements[​](#requirements "Direct link to Requirements") WCPOS : Pro version required for POS checkout Web Payment Gateways : At least one online payment method configured in WooCommerce SSL Certificate : HTTPS required for secure payment processing Modern Browser : Customer device must support modern web standards ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") ### Common Issues[​](#common-issues "Direct link to Common Issues") Checkout link not working * Verify SSL certificate is properly installed * Check that WooCommerce permalinks are configured correctly * Ensure web payment gateways are active and configured * Test with a different browser or device Payment not processing * Confirm web payment gateways are properly configured * Check payment gateway logs for error messages * Verify customer's payment method is supported * Test the web checkout process independently Order not updating in POS * Check internet connection stability * Verify WordPress cron jobs are running properly * Refresh the POS order screen * Check order status in WooCommerce admin Customer can't access checkout * Ensure the checkout link hasn't expired * Verify customer's device has internet connectivity * Check that the order hasn't been cancelled or completed * Test the link on a different device ### Performance Optimisation[​](#performance-optimisation "Direct link to Performance Optimisation") For optimal performance: * **Caching**: Configure caching plugins to exclude checkout pages * **CDN**: Ensure CDN settings don't interfere with checkout process * **Database**: Optimise database for faster order processing * **Hosting**: Use reliable hosting with good uptime ### Getting Help[​](#getting-help "Direct link to Getting Help") For technical support: * Visit the [GitHub repository](https://github.com/wcpos/web-checkout-gateway) to report issues * Check WooCommerce payment gateway documentation * Test your web checkout process regularly * Monitor payment gateway logs for issues ## Screenshots[​](#screenshots "Direct link to Screenshots") Screenshots will be added in a future update to show: * Web Checkout gateway selection and link generation in POS * Customer payment process on the web store checkout * Order completion and receipt processing workflow --- # POS Screen Overview The POS screen is the main interface for selling products. It's where you'll spend most of your time when using WCPOS. ## Screen Layout[​](#screen-layout "Direct link to Screen Layout") ### Header[​](#header "Direct link to Header") The header bar displays: * **Store name** - The name of your connected WooCommerce store * **Connectivity indicator** - Green dot when connected to the server, yellow/red when offline * **User menu** - Click to access settings, switch users, or log out ### Navigation Drawer[​](#navigation-drawer "Direct link to Navigation Drawer") The left sidebar provides quick access to all main screens. The selling screen and the diagnostic/support screens are in the free plugin; the management screens (Products, Orders, Customers, Reports) are part of [WCPOS Pro](/getting-started/free-vs-pro.md). | Icon | Screen | Description | Edition | | ---- | ------------- | ----------------------------------------------------------------------- | ------- | | | **POS** | Main selling interface (you are here) | Free | | | **Products** | Inventory management — edit stock, prices, and product details | Pro | | | **Orders** | Order history — look up, reprint, edit, and refund past orders | Pro | | | **Customers** | Customer management — add and edit customers | Pro | | | **Reports** | Sales reports — end-of-day totals by payment method, cashier, and store | Pro | | | **Logs** | System logs for debugging | Free | | | **Support** | Discord support channel | Free | The version number is displayed at the bottom of the drawer. Free vs Pro screens On the free plugin you can still **select** an existing customer at the till — you just can't open the management screens. Products, Orders, Customers, and Reports unlock with Pro. For a full breakdown see [Free vs Pro](/getting-started/free-vs-pro.md). ## Responsive Layout[​](#responsive-layout "Direct link to Responsive Layout") WCPOS adapts to different screen sizes: ### Desktop / Tablet (Large Screens)[​](#desktop--tablet-large-screens "Direct link to Desktop / Tablet (Large Screens)") On larger screens, the POS displays a **two-column layout**: * **Left column:** Product Panel - search and browse products * **Right column:** Cart Panel - view and manage the current order The columns are **resizable** - drag the divider between them to adjust the proportions. ### Mobile (Small Screens)[​](#mobile-small-screens "Direct link to Mobile (Small Screens)") On smaller screens, the POS uses a **tab-based layout**: * **Products tab:** Browse and add products to cart * **Cart tab:** View cart, manage line items, and checkout Switch between tabs using the navigation bar at the bottom of the screen. ## Main Components[​](#main-components "Direct link to Main Components") ### Product Panel[​](#product-panel "Direct link to Product Panel") The left side of the POS is the [Product Panel](/pos/product-panel/.md), where you: * Search for products by name, SKU, or barcode * Filter products by stock status, category, tags, etc. * Add products to the cart [Learn more about the Product Panel →](/pos/product-panel/.md) ### Cart Panel[​](#cart-panel "Direct link to Cart Panel") The right side of the POS is the [Cart Panel](/pos/cart/.md), where you: * View items in the current order * Edit quantities and prices * Select or add customers * Access order actions (notes, void, checkout) [Learn more about the Cart Panel →](/pos/cart/.md) ### Checkout[​](#checkout "Direct link to Checkout") When you're ready to complete a sale, click **Checkout** to open the [Checkout modal](/pos/checkout/.md): * Apply coupon codes * Select payment method * Process payment * Print or email receipt [Learn more about Checkout →](/pos/checkout/.md) ## Keyboard Shortcuts[​](#keyboard-shortcuts "Direct link to Keyboard Shortcuts") WCPOS supports keyboard shortcuts for faster operation. Access the full list via the Settings modal or see [Keyboard Shortcuts](/settings/store/hotkeys.md). Common shortcuts: | Shortcut | Action | | ------------------ | -------------------- | | `Ctrl + F` | Focus search bar | | `Ctrl + Shift + S` | Open Settings | | `Escape` | Close modal/dialogue | ## Connectivity[​](#connectivity "Direct link to Connectivity") The green indicator in the header shows your connection status: * **Green** - Connected to the WooCommerce server * **Yellow** - Connection issues, retrying * **Red** - Offline mode While offline, you can still browse cached products and customers, and start new orders. Completing orders requires connectivity. --- # Cart Panel The Cart Panel is the right side of the POS screen where you manage the current order. Here you can view items, edit quantities and prices, select customers, and proceed to checkout. ## Interface Overview[​](#interface-overview "Direct link to Interface Overview") ### Customer Selector[​](#customer-selector "Direct link to Customer Selector") At the top of the Cart Panel: * **Customer badge** - Shows the current customer (e.g., "Guest" or customer name) * **Add customer icon** () - Create a new customer * **Display settings** () - Configure cart columns and options Click the customer badge to search for and select a different customer. ### Line Items[​](#line-items "Direct link to Line Items") The main area displays items in the current order: * **QTY** - Quantity (editable) * **Name** - Product name with variation attributes * **Price** - Unit price (editable) * **Total** - Line total See [Line Items](/pos/cart/line-items.md) for details on editing. ### Add to Cart Options[​](#add-to-cart-options "Direct link to Add to Cart Options") Below the line items, you can add special items: * **Add Miscellaneous Product** - Add a custom item with manual price entry * **Add Fee** - Add a fee line (e.g., gift wrapping, service charge) * **Add Shipping** - Add a shipping line with manual cost entry Line Item Types WooCommerce uses three types of line items: `line_item` (products), `fee_line` (fees), and `shipping_line` (shipping). Currently, only manual entry is supported for shipping—the POS does not calculate shipping costs automatically. ### Order Summary[​](#order-summary "Direct link to Order Summary") * **Subtotal** - Total before taxes and fees * **Tax** - Calculated tax amount (if applicable) * **Total** - Final order total ### Order Actions[​](#order-actions "Direct link to Order Actions") At the bottom of the Cart Panel: * **Order Note** - Add a note visible to the customer * **Order Meta** - Add custom metadata or view JSON * **Save to Server** - Save the order to WooCommerce with status `pos-open` See [Order Actions](/pos/cart/order-actions.md) for details. ### Main Buttons[​](#main-buttons "Direct link to Main Buttons") * **Void** (red) - Cancel/delete the current order * **Checkout** (green) - Proceed to payment ### Open Orders[​](#open-orders "Direct link to Open Orders") At the very bottom, a carousel shows all open orders: * Each cart displays its total * Click a cart to switch to it * The current cart is highlighted See [Open Orders](/pos/cart/open-orders.md) for details. ## Display Settings[​](#display-settings "Direct link to Display Settings") Click the sliders icon () to customise the Cart Panel display. ![Cart Settings](/img/pos-cart-settings.png) Cart Panel Display Settings ### Automatically Show Receipt After Checkout[​](#automatically-show-receipt-after-checkout "Direct link to Automatically Show Receipt After Checkout") If enabled, the receipt screen displays automatically after completing a sale. ### Automatically Print Receipt After Checkout[​](#automatically-print-receipt-after-checkout "Direct link to Automatically Print Receipt After Checkout") If enabled, the receipt prints automatically when shown. This saves time by reducing manual print steps. ### Quick Discounts[​](#quick-discounts "Direct link to Quick Discounts") A comma-separated list of discount percentages that appear as quick shortcut buttons. For example, entering `5,10,15,20` adds four buttons that apply percentage discounts to the entire order with a single click. ### Columns[​](#columns "Direct link to Columns") Configure which columns appear in the cart: | Column | Description | | ----------------- | --------------------------- | | **Qty** | Quantity of each item | | **Name** | Product name | | **Price** | Per-unit price | | **Regular Price** | Non-discounted price | | **Subtotal** | Line subtotal (qty × price) | | **Total** | Line total | | **Actions** | Remove item button | Some columns offer extra display options: | Column | Option | | ------------ | ----------------------------- | | **Qty** | Split (allow splitting items) | | **Name** | SKU | | **Price** | On Sale indicator | | **Subtotal** | Tax amount | | **Total** | Tax amount, On Sale indicator | ### Restore Default Settings[​](#restore-default-settings "Direct link to Restore Default Settings") Click to reset all cart display settings to their original defaults. ## Adding Items to Cart[​](#adding-items-to-cart "Direct link to Adding Items to Cart") ### From Product Panel[​](#from-product-panel "Direct link to From Product Panel") Click a product in the [Product Panel](/pos/product-panel/.md) to add it to the cart. For variable products, select the variation first. ### Miscellaneous Products[​](#miscellaneous-products "Direct link to Miscellaneous Products") For items not in your catalogue: 1. Click **Add Miscellaneous Product** 2. Enter a name and price 3. The item is added to the cart ### Fees[​](#fees "Direct link to Fees") To add a fee (e.g., gift wrapping): 1. Click **Add Fee** 2. Enter a name and amount 3. The fee appears as a separate line item ### Shipping[​](#shipping "Direct link to Shipping") To add shipping: 1. Click **Add Shipping** 2. Enter the shipping method name and cost 3. Shipping is added to the order ## Editing Cart Items[​](#editing-cart-items "Direct link to Editing Cart Items") All line items are editable directly in the cart. See [Line Items](/pos/cart/line-items.md) for details on: * Editing quantities * Changing prices * Viewing and editing raw JSON data * Removing items ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [Line ItemsEditing cart line items](/pos/cart/line-items.md) [Open OrdersManaging multiple carts](/pos/cart/open-orders.md) [Order ActionsNotes, metadata, and saving](/pos/cart/order-actions.md) [CheckoutProcessing payment](/pos/checkout/.md) --- # Cart Discounts WCPOS provides several ways for a cashier to discount an order on the fly: quick percentage buttons, direct line-item price edits, and order-level discount fees. For pre-configured promotions with usage rules, see [Coupons](/coupons/.md) (Pro). Changed in v1.9.0 The way POS price changes appear on receipts and in reports changed in v1.9.0. See [What changed in v1.9.0](#what-changed-in-v190) below if you've noticed your "Discount" totals on receipts are now showing as zero. ## Quick Discounts[​](#quick-discounts "Direct link to Quick Discounts") Quick discount buttons let you apply a percentage discount to the entire order with a single tap. To configure them, open the cart [Display Settings](/pos/cart/.md#display-settings) and enter a comma-separated list of percentages in the **Quick Discounts** field. For example, `5,10,15,20` creates four shortcut buttons. When you tap a quick discount button, the percentage is applied across all line items in the cart. ## Line-Item Discounts[​](#line-item-discounts "Direct link to Line-Item Discounts") You can change the price of any individual line item directly in the cart: 1. Click the **Price** field on the line item 2. Enter the new price 3. Press **Enter** to confirm This is useful for price matching, staff discounts, or one-off adjustments. The line item's total updates automatically based on quantity × new price. See [Line Items](/pos/cart/line-items.md) for more on editing cart items. Splitting Items If a customer wants different discounts on portions of the same product (e.g., 3 at full price and 2 discounted), enable the **Split** option in cart [Display Settings](/pos/cart/.md#display-settings) to break a line item into separate lines. ## Order-Level Discounts[​](#order-level-discounts "Direct link to Order-Level Discounts") To apply a flat discount to the entire order (rather than individual items), add a **negative fee**: 1. Click **Add Fee** below the cart items 2. Enter a name (e.g., "Staff discount") 3. Enter the discount amount as a negative number (e.g., `-5.00`) The fee appears as a separate line item and reduces the order total. You can edit the fee's tax status using the three-dot menu if needed. ## POS Discounts vs WooCommerce Coupons[​](#pos-discounts-vs-woocommerce-coupons "Direct link to POS Discounts vs WooCommerce Coupons") The discounts on this page are ad-hoc adjustments cashiers apply at the till; WooCommerce **coupons** are pre-configured promotions with rules and tracking. Here's how they compare at a glance: | | POS Discounts | WooCommerce Coupons (Pro) | | -------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | **How applied** | Quick discount, line price edit, or negative fee | Enter a coupon code in the cart | | **Where configured** | On the fly by the cashier | Pre-configured in **WP Admin → Marketing → Coupons** | | **Tracking** | Recorded as the line price (see [v1.9.0 change](#what-changed-in-v190)) | Tracked as a coupon discount in WooCommerce reports | | **Restrictions** | None — the cashier sets any price | Usage limits, product/category restrictions, minimum spend, expiry, email rules | | **Best for** | Ad-hoc adjustments, price matching | Structured promotions, trackable discounts | Which should I use? For one-off price adjustments, the discounts on this page are simpler. If you need to track discount usage in WooCommerce reports or enforce rules like usage limits, use [Coupons](/coupons/.md). ## How POS Price Changes Interact with Coupons[​](#how-pos-price-changes-interact-with-coupons "Direct link to How POS Price Changes Interact with Coupons") When a cashier sets a custom price on a line item (e.g., reducing $18 to $16), and a coupon is then applied, the coupon calculates against the **POS-discounted price** ($16), not the original ($18). This prevents customers being over-discounted by stacking a cashier discount and a coupon against the original price. * POS-discounted items are treated as "on sale" by WooCommerce. If a coupon has **Exclude sale items** enabled, it will skip POS-discounted items — the same way it skips regular sale items. Developers can override this with the `woocommerce_pos_item_is_on_sale` filter. * Removing a coupon leaves the line at its POS-discounted price. Developer Reference For technical details on how POS price overrides are stored and the available filters, see the [POS Discount Reference](/reference/pos-discounts.md). ## What changed in v1.9.0[​](#what-changed-in-v190 "Direct link to What changed in v1.9.0") If you upgraded from v1.8 and noticed that the **Discount** total on your receipts and reports is now showing **0**, this section explains why and what your options are. ### The change[​](#the-change "Direct link to The change") Before v1.9.0, when a cashier reduced a line price (e.g., $18 → $16), the POS recorded the order with `subtotal = $18` and `total = $16`. WooCommerce then computed `discount_total = $2`, and this appeared on your receipt and in reports as a discount. This caused incorrect totals whenever a coupon was applied on top — the coupon would calculate against the original $18, leading to an over-discount and the customer being undercharged. From v1.9.0, WCPOS aligns with how WooCommerce treats sale prices: the price you set at the till **is** the line subtotal. WooCommerce only counts coupon codes as "discounts" (this matches WC's behavior for products on sale, where the sale price is also baked into the subtotal with no separate discount line). ### What this means for you[​](#what-this-means-for-you "Direct link to What this means for you") * **Receipts** no longer show a separate "Discount" line for line-item price changes. The lower price is the price. * **Reports** show `discount_total = 0` when only POS line-item price changes were used. Only coupon discounts are counted. * **Coupons** now calculate correctly when stacked on POS-discounted items. * **The discount data is still stored** on every order in line-item metadata (`_woocommerce_pos_data`), so historical figures can still be derived if needed. ### If you want discount visibility back[​](#if-you-want-discount-visibility-back "Direct link to If you want discount visibility back") If you need a "total discount given today" figure for your end-of-day reconciliation, the supported way is to use [Coupons](/coupons/.md) instead of line-item price edits for trackable discounts. Set up a "Manager 10%" or "Loyalty $5" coupon in **Marketing → Coupons**, and apply it at the cart. It'll show in your reports natively. We're also evaluating a POS-specific "Total Saved" figure that surfaces line-item price changes separately from coupon discounts. If this matters to your workflow, [let us know](https://wcpos.com/support). ## Known Limitations[​](#known-limitations "Direct link to Known Limitations") * **No automatic discount rules** — the POS doesn't support "buy 2, get 1 free" style automatic discounts. Use WooCommerce coupons for structured promotions. * **Quick discounts are percentage-only** — there's no built-in quick button for fixed-amount discounts. Use a negative fee or edit individual prices instead. --- # Cart Line Items Every item in the cart is a line item that can be edited directly. WCPOS provides flexible inline editing for quantities, prices, and other details. ## Line Item Types[​](#line-item-types "Direct link to Line Item Types") WooCommerce uses three types of line items: | Type | Description | Examples | | ------------------ | ---------------------------- | ----------------------------------- | | **line\_item** | Products from your catalogue | T-shirt, Coffee mug | | **fee\_line** | Additional fees | Gift wrapping, Service charge | | **shipping\_line** | Shipping costs | Standard shipping, Express delivery | note Shipping costs are entered manually. The POS does not calculate shipping rates automatically. ## Editing Line Items[​](#editing-line-items "Direct link to Editing Line Items") ### Quantity[​](#quantity "Direct link to Quantity") Click the quantity field to edit it directly. Type a new number or use the spinner controls. ### Product Name[​](#product-name "Direct link to Product Name") For miscellaneous products and fees, you can edit the name directly by clicking on it. ### Price[​](#price "Direct link to Price") Click the price field to change the unit price. This is useful for: * Applying manual discounts * Price matching * Correcting pricing errors The total updates automatically based on quantity × price. ### Three-Dot Menu[​](#three-dot-menu "Direct link to Three-Dot Menu") Click the **⋮** (three dots) on any line item to access additional options: #### Edit Form[​](#edit-form "Direct link to Edit Form") Opens a detailed edit form for the line item, allowing you to modify all fields. #### Raw JSON View[​](#raw-json-view "Direct link to Raw JSON View") Displays the raw JSON data for the line item. This is extremely helpful for: * **Debugging** - See exactly what data is being sent to WooCommerce * **Troubleshooting** - Identify issues with custom fields or meta data * **Development** - Understand the data structure for integrations ### Remove Item[​](#remove-item "Direct link to Remove Item") Click the red **×** button to remove an item from the cart. ## Variation Attributes[​](#variation-attributes "Direct link to Variation Attributes") For variable products, the selected variation attributes display below the product name: ``` Hoodie Colour: Green Size: Large ``` These attributes are part of the line item data and are included in the order. ## Meta Data[​](#meta-data "Direct link to Meta Data") If you've configured [Meta Data Keys](/pos/product-panel/.md#meta-data-keys) in the Product Panel settings, that data is automatically copied to the line item when the product is added to the cart. You can view this meta data in the Raw JSON view. ## Splitting Line Items[​](#splitting-line-items "Direct link to Splitting Line Items") If enabled in [Display Settings](/pos/cart/.md#display-settings), you can split a line item into multiple lines. This is useful when a customer wants to apply different discounts to portions of the same product. ## Tips[​](#tips "Direct link to Tips") ### Quick Price Adjustments[​](#quick-price-adjustments "Direct link to Quick Price Adjustments") To quickly give a discount: 1. Click the price field 2. Enter the new price 3. Press Enter ### Keyboard Navigation[​](#keyboard-navigation "Direct link to Keyboard Navigation") * **Tab** - Move between editable fields * **Enter** - Confirm edit * **Escape** - Cancel edit ### Batch Edits[​](#batch-edits "Direct link to Batch Edits") For complex orders, consider using the three-dot menu to access the full edit form, which shows all fields at once. --- # Open Orders WCPOS allows you to work with multiple orders simultaneously. This is useful for handling customer holds, switching between transactions, and recovering from interruptions. ## Open Orders Carousel[​](#open-orders-carousel "Direct link to Open Orders Carousel") At the bottom of the Cart Panel, a horizontal carousel displays all open orders: * Each cart shows its **total amount** * The **current order** is highlighted * Click any cart to switch to it * Scroll left/right to see more carts ## Creating a New Order[​](#creating-a-new-order "Direct link to Creating a New Order") A new empty cart is always available. Simply click on an empty cart in the carousel or start adding products when the current cart is empty. ## Switching Between Orders[​](#switching-between-orders "Direct link to Switching Between Orders") Click on any order in the carousel to switch to it. The Cart Panel updates to show the selected order's contents. **Use cases:** * Customer steps away to get another item * Need to help a quick customer while a large order is in progress * Comparing prices or items between orders ## Saving Orders to Server[​](#saving-orders-to-server "Direct link to Saving Orders to Server") Orders exist in two states: ### Local Only[​](#local-only "Direct link to Local Only") By default, new orders are stored only in the local browser/app database. They will persist across page refreshes but: * Are not visible in WooCommerce admin * Will be lost if the local database is cleared * Are not accessible from other devices ### Saved to Server[​](#saved-to-server "Direct link to Saved to Server") Click **Save to Server** to create a WooCommerce order with the status `pos-open`. This: * Creates a real order in WooCommerce * Persists even if the local database is cleared * Can be accessed from other devices * Appears in WP Admin > WooCommerce > Orders When to Save Save orders to the server when: * A customer wants to hold an order for later pickup * You're ending your shift and another cashier will continue * You want a backup in case of app/browser issues ## Recovering Saved Orders[​](#recovering-saved-orders "Direct link to Recovering Saved Orders") If you've saved orders to the server, they can be accessed again by: 1. Opening the **Orders** screen (Pro feature) 2. Filtering by status `pos-open` 3. Reopening the order ## Order Persistence[​](#order-persistence "Direct link to Order Persistence") ### Local Storage[​](#local-storage "Direct link to Local Storage") WCPOS uses IndexedDB to store orders locally. This provides: * Persistence across browser sessions * Fast access without network requests * Offline capability ### Sync with Server[​](#sync-with-server "Direct link to Sync with Server") When you save to server or checkout: * The order is sent to WooCommerce * A confirmation is received * Local and server data are synchronized ## Voiding Orders[​](#voiding-orders "Direct link to Voiding Orders") To remove an open order: 1. Switch to the order you want to remove 2. Click the **Void** button **What happens:** * **Unsaved orders:** Permanently deleted from the local database * **Saved orders:** Moved to Trash in WooCommerce and deleted locally To recover a voided saved order: 1. Go to `WP Admin > WooCommerce > Orders > Trash` 2. Restore the order ## Tips[​](#tips "Direct link to Tips") ### Keep Orders Organized[​](#keep-orders-organized "Direct link to Keep Orders Organized") With multiple open orders, it helps to: * Add customer names to orders for easy identification * Add order notes describing the hold reason * Save important orders to the server ### Shift Handoffs[​](#shift-handoffs "Direct link to Shift Handoffs") When ending a shift with open orders: 1. Save all important orders to the server 2. Add order notes explaining the status 3. The next cashier can access them from the Orders screen ### Offline Considerations[​](#offline-considerations "Direct link to Offline Considerations") If you lose connectivity: * Local orders remain accessible and you can continue adding items * You cannot complete/checkout orders until connectivity is restored * You cannot save orders to the server until reconnected * You cannot create new customers until reconnected --- # Order Actions The Order Actions panel is located at the bottom of the cart in the POS interface. It provides quick access to several essential order management features. ![Order Actions in the POS](/img/order-actions.png) Order Actions in the POS ## Order Note[​](#order-note "Direct link to Order Note") ![Order Note in the POS](/img/order-note.png) Order Note modal in the POS (left) and Order Note in the WP Admin (right) * Opens a dialogue to add a customer note to the order. * Customer notes are visible to the customer and appear on the receipt by default, in the customer's My Account area, and in the `WP Admin > WooCommerce > Orders > Order` under the shipping address. note Order notes are visible to customers. ## Order Meta[​](#order-meta "Direct link to Order Meta") ![Order Meta and JSON View in the POS](/img/order-meta.png) Order Meta and JSON View in the POS * Opens a modal to manage additional metadata for the order. * Features include: * Changing the order currency. * Adding a transaction ID (e.g., from an external payment terminal). * Adding custom meta data for the order. note Additional features will be added to this modal over time, including integration with other WooCommerce plugins. ### What is Meta Data in WooCommerce?[​](#what-is-meta-data-in-woocommerce "Direct link to What is Meta Data in WooCommerce?") Meta data provides extra information about orders and is accessible via the WooCommerce REST API. Developers and plugins use this data to extend functionality, such as integrating third-party services. ### JSON View[​](#json-view "Direct link to JSON View") * View the raw JSON representation of the order, useful for debugging or integration purposes. ## Save to Server[​](#save-to-server "Direct link to Save to Server") * Allows you to save open carts to the server, so they are securely stored and accessible for future use. * Creates a WooCommerce order with status `pos-open`. ### Why save?[​](#why-save "Direct link to Why save?") When a new order is created in the POS, it only exists locally. Saving the order ensures it persists, even if the local database is cleared. See [Open Orders](/pos/cart/open-orders.md) for more details on managing saved orders. ## Void[​](#void "Direct link to Void") * Two Scenarios: * Unsaved Orders: * If the order has not been saved to the server, it will be permanently deleted from the local database. * Saved Orders: * If the order is saved to the server, it will be moved to the Trash folder in WooCommerce and deleted from the local database. * To recover a voided order: * Go to `WP Admin > WooCommerce > Orders > Trash`. ## Checkout[​](#checkout "Direct link to Checkout") * Saves the order to the server and initiates the checkout process. * Opens the [checkout screen](/pos/checkout/.md) to complete the payment. --- # Checkout When you're ready to complete a sale, click the **Checkout** button to open the checkout modal. This is where you process payment and complete the order. ## Checkout Modal Overview[​](#checkout-modal-overview "Direct link to Checkout Modal Overview") The checkout modal displays: * **Order number** - The WooCommerce order ID * **Amount to Pay** - Total amount due * **Checkout Settings** button - Troubleshoot display issues * **Cashier** - Who is processing the order * **Customer** - The customer for this order (clickable link) * **Add Coupon** button - Apply discount codes * **Order summary** - Products, quantities, and totals * **Payment methods** - Available payment options * **Cancel / Process Payment** buttons ## Payment Methods[​](#payment-methods "Direct link to Payment Methods") ### Available in Free Version[​](#available-in-free-version "Direct link to Available in Free Version") The free version of WCPOS includes two payment gateways: * **Cash** - With amount tendered and change calculator * **Card** - For external card terminals ### Additional Gateways (Pro)[​](#additional-gateways-pro "Direct link to Additional Gateways (Pro)") Pro Feature Additional payment gateways require [WCPOS Pro](/getting-started/pro-license.md). With Pro, you can enable: * **Stripe Terminal** - Direct integration with Stripe card readers * **SumUp Terminal** - Integration with SumUp card readers * **Custom Gateways** - Create your own payment integrations See [Payment](/payment/.md) for details on configuring gateways. ### Selecting a Payment Method[​](#selecting-a-payment-method "Direct link to Selecting a Payment Method") Click on a payment method to select it. The form updates to show relevant fields: **Cash:** * **Amount Tendered** - Enter the amount the customer gives you * **Change** - Automatically calculated change to return **Card:** * Process payment on your external card terminal * Click Process Payment to complete ## Coupons[​](#coupons "Direct link to Coupons") The cart includes an **Add Coupon** input above the totals (Pro only). Type the code or search by description; the coupon validates locally and appears as a removable pill. Multiple coupons stack sequentially. See **[Applying Coupons at the Till](/coupons/applying-coupons.md)** for the full workflow — search, pills, sequential discounts, and the table of validation errors and resolutions. For coupon types, validation rules, and setup in WooCommerce, see [Coupons](/coupons/.md). ## Processing Payment[​](#processing-payment "Direct link to Processing Payment") 1. Select a payment method 2. For cash, enter the amount tendered 3. Click **Process Payment** 4. The order is completed and the [receipt](/receipts/at-checkout.md) is shown One payment method per order An order is paid with a single payment method — WCPOS doesn't currently support split or partial payments (e.g. part cash, part card) across one order. Split-payment support is on the [roadmap](https://github.com/orgs/wcpos/projects/4). ## Checkout Settings (Troubleshooting)[​](#checkout-settings-troubleshooting "Direct link to Checkout Settings (Troubleshooting)") The checkout modal uses an iframe/webview to display the WooCommerce Order Pay page. This leverages WooCommerce's existing payment infrastructure, meaning any payment gateway that works with WooCommerce should work in the POS. However, theme and plugin scripts can sometimes interfere. Click **Checkout Settings** to troubleshoot: ![Checkout Settings in the Checkout Modal](/img/checkout-settings.png) Checkout Settings in the Checkout Modal ![Form to disable all styles and scripts](/img/disable-styles-and-scripts.png) Form to disable all styles and scripts ### Disable All Styles and Scripts[​](#disable-all-styles-and-scripts "Direct link to Disable All Styles and Scripts") Nuclear Option This is the nuclear option and should only be used for testing or in rare cases where the developer knows what they are doing. Disabling all wp\_head scripts will remove even the WooCommerce scripts necessary to expand/contract the payment gateways, potentially breaking payment functionality. * **Disable wp\_head** - Removes all scripts/styles from the WordPress header * **Disable wp\_footer** - Removes all scripts/styles from the WordPress footer ### Disable Selected Styles[​](#disable-selected-styles "Direct link to Disable Selected Styles") Selectively disable CSS that may cause display issues: * wp-emoji-styles * wp-block-library * classic-theme-styles * woocommerce-layout * woocommerce-smallscreen * woocommerce-general * etc. ### Disable Selected Scripts[​](#disable-selected-scripts "Direct link to Disable Selected Scripts") Selectively disable JavaScript that may interfere with payment gateways: * wc-add-to-cart * selectWoo * wc-checkout * woocommerce * html5shiv * etc. tip If a payment gateway doesn't display correctly: 1. Try disabling theme styles first 2. Then try disabling WooCommerce scripts that aren't needed 3. Be careful not to disable scripts required by your payment gateway ## Cancel[​](#cancel "Direct link to Cancel") Click **Cancel** to close the checkout modal without completing the order. The order remains as an open cart. ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [ReceiptsAfter checkout, print or email receipts](/receipts/at-checkout.md) [Payment MethodsConfigure payment gateways](/payment/.md) [Custom GatewaysCreate custom payment integrations](/payment/gateways/.md) --- # Product Panel The Product Panel is the left side of the POS screen where you search, browse, and select products to add to the cart. ## Interface Overview[​](#interface-overview "Direct link to Interface Overview") ### Search Bar[​](#search-bar "Direct link to Search Bar") At the top of the panel, the search bar lets you quickly find products by: * **Product name** - Type any part of the product name * **SKU** - Search by Stock Keeping Unit * **Barcode** - Scan or type a barcode number See [Search & Filtering](/pos/product-panel/search-filtering.md) for detailed information. ### Display Settings[​](#display-settings "Direct link to Display Settings") Click the **sliders icon** () next to the search bar to open Display Settings. This allows you to customise which columns and information are shown in the product list. ### Filter Buttons[​](#filter-buttons "Direct link to Filter Buttons") Below the search bar, filter buttons let you narrow down products: * **In Stock** - Show only products with available inventory * **Featured** - Show products marked as featured in WooCommerce * **On Sale** - Show products currently on sale * **Category** - Filter by product category * **Tag** - Filter by product tag * **Brand** - Filter by brand (if using a brand plugin) Active filters appear highlighted. Click a filter again to remove it. ### Product List[​](#product-list "Direct link to Product List") The main area displays your products in a scrollable list. Each row shows: * **Product image** - Thumbnail of the product * **Product name** - With optional details (stock, SKU, categories, etc.) * **Price** - Current selling price (with sale prices shown when applicable) * **Action button** - Add to cart () or select variation () ### Product Types[​](#product-types "Direct link to Product Types") * **Simple products** show a green button to add directly to cart * **Variable products** show a green arrow to open the variation selector See [Variable Products](/pos/product-panel/variations.md) for more details. ### Footer[​](#footer "Direct link to Footer") At the bottom of the Product Panel: * **Tax status** - Shows the current tax calculation basis (e.g., "Tax based on: Shop base address"). Click to view active tax rates. * **Product count** - Shows how many products are displayed (e.g., "Showing 10 of 17") * **Sync button** () - Refresh products from the server. **Long press** for additional options: * **Sync** - Standard refresh from server * **Clear and Refresh** - Clear local data and reload everything ## Display Settings[​](#display-settings-1 "Direct link to Display Settings") Click the sliders icon () to customise the Product Panel display. ![POS Products Settings](/img/pos-products-settings.png) Product Panel Display Settings ### Show Out-of-Stock Products[​](#show-out-of-stock-products "Direct link to Show Out-of-Stock Products") Controls whether products that are currently out of stock are displayed. * **Enabled**: Out-of-stock products remain visible but can't be added to cart * **Disabled**: Out-of-stock products are hidden from the list ### Columns[​](#columns "Direct link to Columns") Configure which columns appear in the product list: | Column | Description | | ---------------------- | ------------------------------------- | | **Image** | Product thumbnail | | **Product** | Product name and details | | **SKU** | Stock Keeping Unit (separate column) | | **Barcode** | Product barcode (separate column) | | **Type** | Product type (simple, variable, etc.) | | **Stock** | Current stock quantity | | **Cost of Goods Sold** | Product cost price | | **Price** | Selling price | | **Actions** | Add to cart button | Two columns have extra display options you can toggle on: | Column | Display options | | ----------- | -------------------------------------------------------------------- | | **Product** | Stock, SKU, Barcode, Categories, Tags, Brands, Attributes, Meta Data | | **Price** | Tax info, On Sale indicator | ### Meta Data Keys[​](#meta-data-keys "Direct link to Meta Data Keys") A meta data key is a custom field stored on a product in WooCommerce. By default these stay on the product — they aren't copied onto the order. This setting lets you carry specific keys over to the cart line item when the product is added. **Example:** a bottle-deposit plugin stores a `_bottle_deposit` value on each product. Add that key here, and whenever the product is added to the cart its deposit value travels with the line item onto the order — so it shows up on the order, the receipt, and any downstream reports. Enter a comma-separated list of meta keys: ``` _bottle_deposit,_custom_field,_tracking_code ``` tip Meta keys are case-sensitive and must match exactly as stored in the product's meta data. When would I use this? Common cases for transferring product meta data to order line items: * **Bottle deposit plugins** — carry the deposit amount onto the order. * **Custom product fields** — pass your own product data through to the order. * **Third-party integration data** — hand values off to other plugins that read order line items. * **Compliance / tracking information** — keep batch, lot, or tracking codes attached to what was sold. ### Restore Default Settings[​](#restore-default-settings "Direct link to Restore Default Settings") Click to reset all display settings to their original defaults. ## Adding Products to Cart[​](#adding-products-to-cart "Direct link to Adding Products to Cart") ### Simple Products[​](#simple-products "Direct link to Simple Products") Click the green button to add a simple product to the cart. Each click adds one more unit. ### Variable Products[​](#variable-products "Direct link to Variable Products") Variable products (e.g., a t-shirt with size and colour options) show a green arrow. Click to: 1. **Quick popover** - Select variation from a dropdown 2. **Expand inline** - Click "Expand" to see all variations in the list See [Variable Products](/pos/product-panel/variations.md) for more details. ### Barcode Scanning[​](#barcode-scanning "Direct link to Barcode Scanning") Connect a USB or Bluetooth barcode scanner to quickly add products. When you scan a barcode, WCPOS automatically searches for and adds the matching product. See [Barcode Scanning](/pos/product-panel/barcode-scanning.md) for setup instructions. ## Why Can't I See Some Products?[​](#why-cant-i-see-some-products "Direct link to Why Can't I See Some Products?") If products are missing from your Product Panel, check: * **POS visibility** - Products set to "Online Only" won't appear in the POS. See [POS Only Products](/products/pos-only-products.md). * **Stock settings** - If "Show Out-of-Stock Products" is disabled in Display Settings, out-of-stock items are hidden. * **Sync status** - New or recently updated products may need a sync. Long press the sync button and select **"Clear and Refresh"**. * **Filters** - Check if you have active filters (Category, Tag, etc.) that might be hiding products. ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [Search & FilteringDetailed search functionality](/pos/product-panel/search-filtering.md) [Barcode ScanningScanner setup and configuration](/pos/product-panel/barcode-scanning.md) [Variable ProductsWorking with product variations](/pos/product-panel/variations.md) --- # Barcode Scanning Most barcode scanners behave like a keyboard connected to your device. When you scan a barcode, the WCPOS detects that the characters were entered faster than normal typing. It uses these "fast key presses" to identify the input as a barcode scan. ## Configuring Barcode Scanning[​](#configuring-barcode-scanning "Direct link to Configuring Barcode Scanning") Since a barcode scan happens very fast, the POS can tell the difference between a barcode and something typed in by hand. In the POS settings, you'll find options for fine-tuning how barcode detection works. ![Barcode Scanning Settings in the POS Settings](/img/barcode-scanning-settings.png) Barcode Scanning Settings in the POS Settings | Setting | Purpose | Typical value | | ------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | | **Average input time** | How fast the input must be to count as a barcode | A short interval — fast enough that hand-typing won't trigger it | | **Minimum length** | How long the continuous string of characters must be to be treated as a barcode | Match the shortest barcode you use (e.g. 8 for EAN-8) | | **Prefix/Suffix removal** | Strips extra characters your scanner adds (a prefix or suffix) so only the main barcode remains | Leave empty unless your scanner is configured to add them | ## What Happens When a Barcode is Detected?[​](#what-happens-when-a-barcode-is-detected "Direct link to What Happens When a Barcode is Detected?") When the POS detects a barcode, it looks in its local database to find a matching product or product variation. There are three possible outcomes: Multiple matches usually means a data issue If more than one product shares the same barcode, the POS can't know which to add, so it drops the code into the search bar for you to choose. When this happens it's usually a sign your product data needs tidying up — each product should have a **unique** barcode. ## Understanding Product Synchronisation[​](#understanding-product-synchronisation "Direct link to Understanding Product Synchronisation") ### Progressive Product Downloading[​](#progressive-product-downloading "Direct link to Progressive Product Downloading") WCPOS doesn't load all your products at once. Instead, it downloads them in small batches. This approach prevents slowdowns and makes sure your store runs smoothly. Over time, as you use the POS and conduct searches, more of your products are stored locally on your device. See [Product Synchronisation](/products/sync.md) for more details. ### Why It Matters for Barcode Scanning[​](#why-it-matters-for-barcode-scanning "Direct link to Why It Matters for Barcode Scanning") When you scan a barcode that isn't yet stored locally, the POS will "go online" to your WooCommerce store to find it. As part of this process, it will download that product (and others in small batches) and save them. This means that over time, the POS becomes faster and more efficient as more products are stored locally. ### How to Speed Up the Process[​](#how-to-speed-up-the-process "Direct link to How to Speed Up the Process") Simply searching for products in the POS helps it download more of your inventory. The more you use the search — and the more you scan—the more complete your local database becomes. ## F.A.Q.[​](#faq "Direct link to F.A.Q.") Why do I get '0 products found locally' when I scan a barcode? Not all products are available locally right from the start. The POS gradually downloads products from your online store and stores them on your device. If the product you just scanned isn't stored yet, the search triggers the POS to look it up online and then download it so it's available in the future. Does the POS generate and print barcodes? No, not at this time. Our POS is designed to scan and read existing barcodes, but it does not include functionality to create or print them. If you need to generate barcodes for your products, you can use third-party WooCommerce plugins that specialise in barcode creation and printing. Some examples include: * [EAN for WooCommerce](https://wordpress.org/plugins/ean-for-woocommerce/) * [A4 Barcode Generator](https://wordpress.org/plugins/a4-barcode-generator/) Once you have generated barcodes for your products, you can easily scan them at the register to speed up the checkout process in the POS. --- # Meta Data Keys ## What is product meta data?[​](#what-is-product-meta-data "Direct link to What is product meta data?") Every WooCommerce product can carry extra fields beyond its name and price — things like a size, an engraving message, a supplier code, or data added by other plugins. WooCommerce stores these as **meta data**: each entry has a **key** (the field's name, e.g. `engraving`) and a **value** (e.g. `"Happy Birthday"`). ## What the Meta Data Keys setting does[​](#what-the-meta-data-keys-setting-does "Direct link to What the Meta Data Keys setting does") By default, when you add a product to the cart only its standard details are copied. The **Meta Data Keys** setting (Product Panel → Settings) lets you choose which product meta keys should be **copied onto the cart line item** — and therefore saved on the order. For example, adding `engraving` to the list means that whenever you add an engravable product to the cart, its engraving value travels with it onto the order. ## Choosing keys[​](#choosing-keys "Direct link to Choosing keys") Start typing in the Meta Data Keys field: * **Suggestions** are the meta keys found on the products already synced to this device. * If the key you need isn't listed (for example, it only exists on products not yet synced), just type the exact key name and choose **Add "…" as a custom key**. * Selected keys appear as chips; remove one by tapping its ✕. The keys you choose are saved with your other panel settings and apply to both the table and grid (tile) views. ## Tips[​](#tips "Direct link to Tips") * Meta keys are case-sensitive and must match the key stored on the product exactly. * Keys beginning with an underscore (e.g. `_size`) are "hidden"/internal WooCommerce meta. They still work here if that's where your data lives. --- # Search & Filtering Finding the right products quickly is essential for efficient point-of-sale operations. WCPOS provides powerful search and filtering capabilities to help you locate products instantly, even with large inventories. ![Product search and filtering interface](/img/product-search-and-filtering.png) Product search and filtering interface in WCPOS ## Product Search[​](#product-search "Direct link to Product Search") ### Unified Search Field[​](#unified-search-field "Direct link to Unified Search Field") WCPOS features a single search field that simultaneously searches across multiple product attributes: * **Product Name** - Searches the product title and description * **SKU** - Matches product postmeta `_sku` field * **Barcode** - Searches configured barcode field, which can be any postmeta field. The legacy setting is `_sku`, but this will be changed to `_global_unique_id` in the future. Simply type your search term into the "Search Products" field, and the POS will instantly filter results across all these fields. ### Tokenized Search Technology[​](#tokenized-search-technology "Direct link to Tokenized Search Technology") The search functionality uses the [FlexSearch library](https://github.com/nextapps-de/flexsearch) with advanced tokenization capabilities: * **Forward Tokenization** - Matches partial words from the beginning (e.g., searching "blue" will find "blueberry") * **Performance Optimized** - Uses a performance preset for fast search results * **Language Aware** - Adapts to your store's configured language * **Lazy Initialization** - Optimizes memory usage by loading search indexes only when needed Search matches the start of words Because matching is forward (prefix) based, search finds the **start** of a word or token, not the middle — searching "berry" won't find "blueberry", and a hyphen starts a new token (so "ABC-XYZ" is found by "ABC" or "XYZ", but not "BCX"). For languages that don't separate words with spaces (e.g. Chinese, Japanese), tokenization is unreliable — search by **barcode or SKU** instead. ### How Search Works[​](#how-search-works "Direct link to How Search Works") When you type in the search field, the POS: 1. **Tokenizes** your input into searchable terms 2. **Searches locally** stored product data first for instant results 3. **Queries the server** if no local matches are found, then downloads and stores new products for future searches 4. **Updates results** in real-time as you type This approach ensures fast search performance while progressively building a complete local product database. ## Product Filtering[​](#product-filtering "Direct link to Product Filtering") ### Filter Bar[​](#filter-bar "Direct link to Filter Bar") Below the search field, you'll find interactive filter toggles and dropdown menus that allow you to narrow down products by specific criteria. ### Available Filters[​](#available-filters "Direct link to Available Filters") #### Stock Status[​](#stock-status "Direct link to Stock Status") Filter products based on their inventory status: * **In Stock** - Products with available inventory * **Out of Stock** - Products with zero inventory * **Backorder** - Products available for backorder #### Featured Products[​](#featured-products "Direct link to Featured Products") Toggle to show only products marked as "Featured" in your WooCommerce store. #### On Sale Products[​](#on-sale-products "Direct link to On Sale Products") Filter to display only products currently on sale or with active discounts. #### Category[​](#category "Direct link to Category") Use the category dropdown to filter products by their assigned product categories. This helps you quickly find products within specific departments or product lines. #### Tag[​](#tag "Direct link to Tag") Filter by product tags to find items with specific attributes or characteristics you've defined in your WooCommerce store. ### Using Filters[​](#using-filters "Direct link to Using Filters") * **Toggle Filters** - Click any filter button to activate it (active filters appear highlighted) * **Multiple Filters** - You can combine multiple filters to narrow your search further * **Clear Filters** - Click an active filter again to deactivate it * **Search + Filter** - Use filters together with the search field for precise product location ## Barcode Configuration[​](#barcode-configuration "Direct link to Barcode Configuration") ### Search Fields[​](#search-fields "Direct link to Search Fields") The search functionality automatically includes your configured barcode field. The barcode field used for searching depends on your POS settings configuration. ## F.A.Q.[​](#faq "Direct link to F.A.Q.") What is the \_global\_unique\_id field for barcodes? The `_global_unique_id` field is a new barcode field that WooCommerce recently added to provide better barcode standardization across stores. **Key Points:** * **Modern Standard**: This field was designed specifically for global barcode identification * **POS Configuration**: You can configure the POS to use `_global_unique_id` as the barcode field in the POS settings * **Legacy vs. New**: The legacy barcode setting uses the `_sku` field, but this will change to `_global_unique_id` in future versions * **Flexibility**: You can configure any product meta field as your barcode field if you're using third-party barcode plugins * **One field per product**: The POS searches a single configured barcode field, and WooCommerce stores one barcode value per product (or per variation). If you need multiple codes on a product, store them in a custom field and point the barcode setting at it * **Future Default**: `_global_unique_id` will become the default barcode field in future POS updates To configure which field the POS uses for barcodes, visit your POS settings in the WordPress admin area. Why don't I see all my products when I search? WCPOS uses progressive product downloading to maintain performance. If you don't see a product: 1. **Try searching for it** - This will trigger the POS to look for it on your server 2. **Wait for download** - The POS will download the product and others in small batches 3. **Search again** - Once downloaded, the product will appear in future searches This process ensures your POS remains fast and responsive even with thousands of products. Learn more about this in our [Product Synchronisation](/products/sync.md) guide. Can I search for partial product names or SKUs? Yes! The tokenized search uses forward matching, which means: * Searching "blue" will find products with "blueberry", "blue shirt", etc. * Searching "ABC" will find SKUs like "ABC123", "ABC-XYZ", etc. * You don't need to type complete words or codes The search is designed to find products quickly with minimal typing. --- # Variable Products Variable products in WooCommerce are products that have multiple options, such as different sizes, colors, or materials. WCPOS provides several ways to work with variable products efficiently. ## Identifying Variable Products[​](#identifying-variable-products "Direct link to Identifying Variable Products") In the Product Panel, variable products are distinguished by: * **Arrow button** () instead of the plus button () used for simple products * **Attribute options** displayed below the product name (e.g., "Colour: Blue, Green, Red") * **"Expand" link** to view all variations inline ## Adding Variable Products to Cart[​](#adding-variable-products-to-cart "Direct link to Adding Variable Products to Cart") ### Method 1: Quick Popover[​](#method-1-quick-popover "Direct link to Method 1: Quick Popover") Click the green arrow button on a variable product to open a popover with dropdown menus for each attribute: 1. Click the button 2. Select options from each dropdown (e.g., Size: Large, Colour: Blue) 3. The matching variation is added to the cart This is the fastest method when you know exactly which variation you need. ### Method 2: Expand Inline[​](#method-2-expand-inline "Direct link to Method 2: Expand Inline") Click the **"Expand"** link on a variable product to show all its variations directly in the product list: 1. Click **Expand** below the product name 2. All variations appear as separate rows beneath the parent product 3. Click the button on any variation to add it to the cart 4. Click **Collapse** to hide the variations again This method is useful when you want to see all available options, their individual stock levels, and prices. ### Method 3: Barcode Scanning[​](#method-3-barcode-scanning "Direct link to Method 3: Barcode Scanning") Each product variation can have its own unique barcode. When you scan a variation's barcode: * If exactly one variation matches, it's added directly to the cart * If multiple variations share the barcode, the search bar shows matching results See [Barcode Scanning](/pos/product-panel/barcode-scanning.md) for more details. ## Variation Information[​](#variation-information "Direct link to Variation Information") Each variation can display: * **Variation attributes** - The specific options for this variation (e.g., "Size: Large, Colour: Blue") * **SKU** - Unique identifier for the variation (may differ from parent product) * **Stock quantity** - Individual stock level for the variation * **Price** - Variations can have different prices than the parent or each other ## Variations in the Cart[​](#variations-in-the-cart "Direct link to Variations in the Cart") When a variation is added to the cart, it displays: * **Product name** from the parent product * **Variation attributes** below the name * **Price** for that specific variation You can edit the line item just like any other product in the cart. ## Tips for Efficient Variation Selection[​](#tips-for-efficient-variation-selection "Direct link to Tips for Efficient Variation Selection") ### Use Barcode Scanning[​](#use-barcode-scanning "Direct link to Use Barcode Scanning") If your variations have individual barcodes (recommended), scanning is the fastest way to add them to the cart. ### Configure Display Options[​](#configure-display-options "Direct link to Configure Display Options") In the Product Panel [Display Settings](/pos/product-panel/.md#display-settings), enable the **Attributes** option to show variation attributes directly in the product list without expanding. ### Keyboard Navigation[​](#keyboard-navigation "Direct link to Keyboard Navigation") When the variation popover is open, you can use keyboard arrow keys to navigate options and Enter to select. ## F.A.Q.[​](#faq "Direct link to F.A.Q.") Why can't I see a specific variation? Check that the variation: * Is published and not in draft status * Is set to "In Stock" or has stock quantity > 0 (if stock management is enabled) * Has all required attributes defined Also ensure you haven't filtered out the product with the "In Stock" filter if the variation is out of stock. How do I add barcodes to individual variations? In WooCommerce, edit the variable product and expand each variation. You can add a unique barcode to each variation's barcode field (typically `_sku` or `_global_unique_id` depending on your configuration). --- # End-of-Day Reconciliation At the end of a shift you close out the till: count the cash, compare it to what the POS says you took, check card totals, and file the record. WCPOS tells you what the drawer *should* hold — the cashier counts it and reconciles manually. Pro Feature The Reports screen used for reconciliation requires [WCPOS Pro](/getting-started/pro-license.md). Without Pro, reconcile from `WP Admin → WooCommerce → Analytics`. ## The short version[​](#the-short-version "Direct link to The short version") 1. **Stop taking sales** so nothing lands mid-count. 2. **Count the drawer** — every denomination. That's your *counted cash*. 3. **Open Reports**, filter to today (and your cashier/store), and read the **Cash** and **Card** figures from the Sales Summary. 4. **Reconcile cash:** *Opening float + cash sales − cash refunds − cash drops* should equal your counted cash. 5. **Reconcile card:** the card terminal's batch total should match the POS card total. Settle the batch if your terminal is manual. 6. **Print the report**, drop the cash, put tomorrow's float back, and sign off. No built-in till sessions WCPOS has no opening-float field, drawer-counting, or automated variance calculation — keep the float and drops on a sheet or spreadsheet at the till. ## Want the full walkthrough?[​](#want-the-full-walkthrough "Direct link to Want the full walkthrough?") The complete walkthrough covers variance handling, multi-cashier and multi-store closes, what to do when a sale lands mid-close, and best practices for an auditable trail. [Full Reconciliation WalkthroughStep-by-step close, variance handling, and multi-cashier/store scenarios](/reports/reconciliation.md) [ReportsThe Reports screen reference — filters, columns, summary panel](/reports/.md) [RefundsIssuing refunds during the shift](/orders/refunds.md) --- # Refunds at the Till Need to give money back at the register? WCPOS lets you refund a WooCommerce order without leaving the POS — full or partial, back to the original payment method or as cash from the till. Pro Feature Issuing refunds from the POS requires [WCPOS Pro](/getting-started/pro-license.md). Without Pro, refund from `WP Admin → WooCommerce → Orders`. ## The short version[​](#the-short-version "Direct link to The short version") 1. **Open the refund form** — from the Orders list, click the three-dot menu on the order and choose **Refund**; or open the order and click **Refund** in the footer. 2. **Set the quantities** — enter a **Refund Qty** for each line (set every line to its full quantity for a whole-order refund, or just a few lines for a partial). Add an optional **Custom Amount** and **Reason** if needed. 3. **Choose where the money goes:** * **Refund to *(gateway)*** — sends the funds back to the original card/wallet, for gateways that support it (e.g. Stripe Terminal, Vipps MobilePay). * **Refund via cash** — record cash handed back from the till. Used automatically for cash sales. 4. **Confirm** — press **Process Refund** and confirm the amount. The order updates immediately. Refunds need a live server connection — unlike checkout, they can't be queued offline. ## Want the full details?[​](#want-the-full-details "Direct link to Want the full details?") The complete guide covers which order statuses can be refunded, how the refund form calculates tax, gateway-vs-cash decision rules, what happens to receipts and order status afterward, and the cashier/store audit trail. [Full Refunds GuideEverything about issuing refunds, gateway vs cash, and what happens afterward](/orders/refunds.md) [Payment GatewaysWhich gateways support refunds back to the original method](/payment/.md) [ReceiptsFiscal vs. live receipts on refunded orders](/receipts/at-checkout.md) --- # Products Management Pro Feature The Products screen requires [WCPOS Pro](/getting-started/pro-license.md). Free users can view and add products to cart from the [POS Product Panel](/pos/product-panel/.md), but cannot edit inventory or prices. The Products screen is a dedicated inventory management interface. Unlike the [POS Product Panel](/pos/product-panel/.md) (which is for selling), this screen is designed for managing your product catalogue. Coming soon Stock control to prevent overselling is in progress — it will block adding out-of-stock items to the cart and validate stock at checkout, respecting your WooCommerce backorder settings. [Follow it on the roadmap →](https://github.com/orgs/wcpos/projects/4) ## Products Screen vs POS Product Panel[​](#products-screen-vs-pos-product-panel "Direct link to Products Screen vs POS Product Panel") | Feature | POS Product Panel | Products Screen | | ---------------- | -------------------- | ------------------ | | **Purpose** | Add products to cart | Manage inventory | | **Stock** | View only | Edit inline | | **Prices** | View only | Edit inline | | **Actions** | Add to cart | Edit, Sync, Delete | | **Available in** | Free + Pro | Pro only | ## Interface Overview[​](#interface-overview "Direct link to Interface Overview") ### Search & Filters[​](#search--filters "Direct link to Search & Filters") At the top of the screen: * **Search bar** - Find products by name, SKU, or barcode * **Filter buttons** - Stock Status, Featured, On Sale, Category, Tag, Brand * **Display settings** () - Configure visible columns ### Product List[​](#product-list "Direct link to Product List") The main area displays your products in a scrollable table: * **Image** - Product thumbnail * **Product name** - With optional SKU, barcode, attributes * **Stock** - Editable stock quantity with "Manage" toggle * **Stock Status** - In Stock (green), Out of Stock (red), Backorder * **Categories** - Product category badges * **Prices** - Current price, regular price, sale price (all editable) * **Actions** - Three-dot menu with Edit, Sync, Delete ### Variable Products[​](#variable-products "Direct link to Variable Products") Variable products show: * Attribute options (Colour, Size, etc.) * "Expand" link to view all variations * Individual variation rows with separate stock/prices ### Footer[​](#footer "Direct link to Footer") * **Tax status** - Current tax calculation basis * **Product count** - "Showing X of Y" with sync button (). **Long press** the sync button for Clear and Refresh option ## Key Features[​](#key-features "Direct link to Key Features") ### Inline Stock Editing[​](#inline-stock-editing "Direct link to Inline Stock Editing") Click directly on the stock quantity to edit it: 1. Click the stock number 2. Enter the new quantity 3. Press Enter to save Changes sync to WooCommerce automatically. ### Manage Stock Toggle[​](#manage-stock-toggle "Direct link to Manage Stock Toggle") The "Manage" toggle controls whether WooCommerce tracks inventory for this product: * **On** - Stock levels are tracked and decremented on sales * **Off** - Product is always available (infinite stock) ### Inline Price Editing[​](#inline-price-editing "Direct link to Inline Price Editing") Click on any price field to edit: * **Price** - Current selling price * **Regular Price** - Non-discounted price * **Sale Price** - Discounted price (when on sale) ### Cost of Goods Sold[​](#cost-of-goods-sold "Direct link to Cost of Goods Sold") WooCommerce's Cost of Goods Sold (COGS) feature lets you track the cost price of each product. WCPOS surfaces this data on the Products screen. To view cost prices, enable the **Cost of Goods Sold** column in [Display Settings](#display-settings) (). The column shows the cost price alongside your selling prices, making it easy to review margins at a glance. Pro Feature [WCPOS Pro](/getting-started/pro-license.md) users can **edit** the cost price directly from the Products screen — click the cost value to update it inline, just like stock and price fields. WooCommerce Requirement Cost of Goods Sold must be enabled in your WooCommerce store: go to **WooCommerce > Settings > Advanced > Features** and enable the Cost of Goods Sold option. This requires a recent version of WooCommerce with the Cost of Goods Sold feature enabled. See the WooCommerce documentation for setup details. ### Product Actions[​](#product-actions "Direct link to Product Actions") Click the three-dot menu (⋮) for each product: * **Edit** - Open the product edit modal * **Sync** - Refresh this product from WooCommerce * **Delete** - Remove product from local database note Deleting a product from the POS only removes it locally. The product remains in WooCommerce and will reappear on the next sync. ## Display Settings[​](#display-settings "Direct link to Display Settings") Click the sliders icon () to customise the Products screen. ![Products Settings](/img/products-page-settings.png) Products Display Settings ### Available Columns[​](#available-columns "Direct link to Available Columns") | Column | Description | Display Options | | ---------------------- | -------------------------------------- | ------------------------ | | **Image** | Product thumbnail | - | | **ID** | WooCommerce product ID | - | | **Product** | Product name | SKU, Barcode, Attributes | | **Type** | Simple, variable, grouped, etc. | - | | **SKU** | Stock Keeping Unit | - | | **Barcode** | Product barcode | - | | **Stock** | Current quantity (editable) | - | | **Stock Status** | In Stock / Out of Stock / Backorder | - | | **Categories** | Product categories | - | | **Tags** | Product tags | - | | **Brands** | Brand info (if plugin active) | - | | **Cost of Goods Sold** | Product cost price (editable with Pro) | - | | **Price** | Current selling price (editable) | Tax info | | **Regular Price** | Non-discounted price (editable) | Tax info | | **Sale Price** | Discounted price (editable) | Tax info | | **Date Created** | When product was created | - | | **Date Modified** | Last modification date | - | | **Actions** | Edit, Sync, Delete buttons | - | ### Restore Default Settings[​](#restore-default-settings "Direct link to Restore Default Settings") Click to reset all display settings to their original defaults. ## Filtering Products[​](#filtering-products "Direct link to Filtering Products") Use the filter buttons to narrow your view: * **Stock Status** - In Stock, Out of Stock, Backorder * **Featured** - Products marked as featured * **On Sale** - Products currently on sale * **Category** - Filter by product category * **Tag** - Filter by product tag * **Brand** - Filter by brand (if using brand plugin) ## Sorting[​](#sorting "Direct link to Sorting") Click any column header to sort by that column. Click again to reverse the sort order. ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [Product SynchronisationHow products sync with WooCommerce](/products/sync.md) [POS Product PanelThe selling interface](/pos/product-panel/.md) [Barcode ScanningSetting up barcode scanning](/pos/product-panel/barcode-scanning.md) --- # POS Only Products POS Only Products is a feature that lets you control whether products appear in your online store, your POS, or both. This is useful when you have different product catalogues for online and in-store sales. ## Overview[​](#overview "Direct link to Overview") When enabled, each product gets a **POS Visibility** setting with three options: | Visibility | Online Store | POS | | -------------------------- | ------------ | ------- | | **POS & Online** (default) | Visible | Visible | | **POS Only** | Hidden | Visible | | **Online Only** | Visible | Hidden | ## When to Use This Feature[​](#when-to-use-this-feature "Direct link to When to Use This Feature") Enable POS Only Products if you need to: * **Sell in-store exclusives** - Products only available when customers visit your physical store * **Hide online-only items from POS** - Digital products, pre-orders, or items that shouldn't be sold in-store * **Manage different catalogues** - Separate product ranges for online and retail channels * **Control promotional items** - In-store-only specials or online-exclusive deals tip If all your products should appear in both channels, you don't need this feature. Leave it disabled for better performance. ## Enabling the Feature[​](#enabling-the-feature "Direct link to Enabling the Feature") 1. Go to **WP Admin > POS > Settings > General** 2. Enable **"Enable POS Only Products"** 3. Save changes For more details on General Settings, see [WP Admin General Settings](/settings/wp-admin/general.md). Performance Impact Only enable this setting if you need it. When enabled, it adds an extra database lookup for every product request, which can impact performance on stores with large catalogues. ## Setting Product Visibility[​](#setting-product-visibility "Direct link to Setting Product Visibility") ### Individual Products[​](#individual-products "Direct link to Individual Products") To set visibility for a single product: 1. Go to **WP Admin → Products** and edit a product 2. In the **Product data** panel, look for **POS Visibility** 3. Select your desired option: * **POS & Online** - Product appears everywhere (default) * **POS Only** - Product hidden from online store * **Online Only** - Product hidden from POS 4. Click **Update** to save ![POS Visibility setting in the product data panel](/img/pos-only-products.png) POS Visibility setting in the Product data panel ### Bulk Editing[​](#bulk-editing "Direct link to Bulk Editing") To change visibility for multiple products at once: 1. Go to **WP Admin → Products** 2. Select the products you want to modify using the checkboxes 3. From the **Bulk actions** dropdown, select **Edit** 4. Click **Apply** 5. In the bulk edit panel, find the **POS Visibility** dropdown 6. Select your desired visibility option 7. Click **Update** ![Bulk editing POS visibility for multiple products](/img/bulk-edit-pos-only-products.png) Bulk editing POS visibility from the Products list ### Variable Products[​](#variable-products "Direct link to Variable Products") For variable products, you can set visibility at both the parent product level and for each individual variation. This gives you fine-grained control - for example, you could show all variations online but only certain colours or sizes in-store. ![POS Visibility settings for individual variations](/img/pos-only-variations.png) Each variation has its own POS Visibility setting ## How It Affects the POS[​](#how-it-affects-the-pos "Direct link to How It Affects the POS") When a product is set to **Online Only**: * It won't appear in the [Product Panel](/pos/product-panel/.md) * It won't be found via search or barcode scanning * It cannot be added to cart in the POS When a product is set to **POS Only**: * It won't appear on your WooCommerce store frontend * It won't be included in online search results * Customers cannot purchase it online note If you've recently changed a product's visibility and it's still appearing (or not appearing) in the POS, try a sync. Long press the sync button and select **"Clear and Refresh"** to reload all product data. ## Common Use Cases[​](#common-use-cases "Direct link to Common Use Cases") #### In-Store Only Gift Cards Physical gift cards that need to be activated at the register: 1. Create the gift card product 2. Set visibility to **POS Only** 3. The card won't appear online but staff can sell it in-store #### Online Pre-Orders Products available for pre-order online but not yet in stock: 1. Create the pre-order product 2. Set visibility to **Online Only** 3. Customers can pre-order online, but it won't clutter the POS #### Wholesale vs Retail If you use the same WooCommerce store for wholesale and retail: 1. Set wholesale-only products to **Online Only** (for B2B portal access) 2. Set retail exclusives to **POS Only** 3. Keep regular products as **POS & Online** ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") Products still appearing after setting to Online Only 1. Open the POS 2. Long press the sync button at the bottom of the Product Panel 3. Select **"Clear and Refresh"** 4. Wait for products to reload Setting not showing on products Make sure the feature is enabled: 1. Go to **WP Admin > POS > Settings > General** 2. Verify **"Enable POS Only Products"** is checked 3. Save settings if you made changes ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [WP Admin General SettingsEnable the feature](/settings/wp-admin/general.md) [Product PanelThe POS product browsing interface](/pos/product-panel/.md) [Product SynchronisationHow products sync between WooCommerce and POS](/products/sync.md) --- # Product Synchronisation One of the significant aspects of the WCPOS (Point of Sale) system is its approach to data management. It provides an efficient way to handle a large volume of product data. This guide explains how products are downloaded and synchronised within WCPOS. ## Local Storage of Products[​](#local-storage-of-products "Direct link to Local Storage of Products") WCPOS fetches products from your WooCommerce store and stores them locally on your device. This approach means that once a product is downloaded, it doesn't need to be fetched repeatedly. As you continue using the POS, it will progressively download all the products from your WooCommerce store, creating a local database of your products. ## Batch Downloading of Products[​](#batch-downloading-of-products "Direct link to Batch Downloading of Products") For most stores, attempting to download more than about 50 products at once could lead to high server load, slower response times, or even server crashes. To prevent this, WCPOS is designed to download products in small batches, usually around 50 products at a time. This process continues until the entire inventory has been locally stored, ensuring that a large volume of data can be managed without putting undue stress on your server. ## Using the Product Search[​](#using-the-product-search "Direct link to Using the Product Search") An effective way to initiate the batch downloading of products is by using the product search function. Each time you conduct a product search, the POS system fetches and stores another batch of products. This strategy not only helps you gradually download new products, but also enhances the speed and efficiency of the search function as more products are stored locally. ## Conclusion[​](#conclusion "Direct link to Conclusion") It's important to understand that all your products won't appear at once in your POS system, and this is completely normal. Over time, by using the product search and other POS operations, you'll download all your products. For more detailed information on how WCPOS operates, see [Architecture](/reference/architecture.md). WCPOS is designed to optimise server load and operational efficiency. The progressive product downloading feature ensures a smooth, efficient, and user-friendly retail management experience. tip If you're experiencing persistent sync issues that a normal sync can't resolve, you can [clear all local data](/support/troubleshooting/clear-local-data.md) to force a fresh download of your entire store. ## F.A.Q.[​](#faq "Direct link to F.A.Q.") How do I get more products to load? Product synchronisation in the POS can be triggered in several ways: * When the POS is first loaded. * Each time you execute a product search. * Applying a filter, for example, by category or tag. * Scrolling to the bottom of the product list. * Pressing the sync button manually (short press for sync, **long press** for Clear and Refresh option). * Furthermore, the POS will automatically sync every 5 minutes. Once all the products are downloaded, future syncs will only fetch the products that have been updated since the last sync. I have scrolled to the bottom and it's still not showing all products There could be a couple of reasons why not all products are showing: * The POS will hide out-of-stock items by default. This setting can be altered in the product display settings if you wish to show out-of-stock items. * The WooCommerce REST API is only compatible with the standard WooCommerce product types, which are simple, variable, grouped, and external. If you're using a custom product type, they might not display in the POS. --- # Receipts WCPOS includes a complete template system for receipts, invoices, gift receipts, packing slips, kitchen tickets and more — all managed in **WP Admin → POS → Templates**. Just want to change your receipt? Start at **[Customise Your Receipt](/receipts/customise.md)**. It walks through the three easiest ways to do it — picking a different bundled template, asking AI to tweak one, or editing by hand. ## Template engines[​](#template-engines "Direct link to Template engines") WCPOS supports three template engines. The engine is chosen when you create a template or click **Use Template** on a gallery card, and **cannot be changed afterward** — start a new template if you want to switch engines. #### Logicless HTML (recommended) Mustache-style `{{variable}}` placeholders inside plain HTML. Renders client-side, so receipts **work offline**. Use for browser print and PDF receipts. #### Thermal XML XML templates that produce both a screen preview and **ESC/POS commands** for thermal receipt printers. Same template, two outputs. Use for Epson, Star, and other thermal printers. #### Legacy PHP Server-side PHP templates using WooCommerce functions. Kept for backward compatibility with existing `yourtheme/woocommerce-pos/receipt.php` overrides. Requires a server connection to render. ## Template gallery[​](#template-gallery "Direct link to Template gallery") The gallery ships with ready-made templates you can use as-is or customise. Filter by **category** (Receipt, Invoice, Gift Receipt, Kitchen Ticket, Quote / Purchase Order), **format** (HTML / ESC/POS), and **direction** (LTR / RTL); preview with your store's real data. Each card's footer has a **Preview** link and a primary **Use Template** button — clicking Use Template creates an editable copy in *Your Templates*. ### HTML templates[​](#html-templates "Direct link to HTML templates") For browser print and PDF receipts. Render client-side, so they work offline. #### Standard Receipt **HTML** · Default receipt — logo, store identity, items, totals, payment. #### Standard Receipt (RTL) **HTML · RTL** · Right-to-left counterpart for Arabic, Hebrew, Persian, Urdu. #### Minimal / Modern **HTML** · Same essentials as Standard, packed into less vertical space. #### Detailed Receipt **HTML** · Full tax invoice — SKU column, unit price, per-rate tax breakdown, addresses. #### Gift Receipt **HTML** · Items only, prices hidden. Includes gift message and return policy. #### Invoice **HTML** · Full-page A4/Letter invoice with optional "How to pay" panel for unpaid orders. #### Packing Slip **HTML** · Warehouse companion — items + quantities, ship-to, no prices. #### Quote / Estimate **HTML** · Pre-sale document with pricing and terms — no payment section. #### Narrow Receipt **HTML** · Monospace receipt for narrow paper or HTML-capable thermal printers. ### Thermal (ESC/POS) templates[​](#thermal-esc-pos-templates "Direct link to Thermal (ESC/POS) templates") For Epson, Star, and other thermal receipt printers. #### Simple Thermal Receipt (58mm) **Thermal · 58mm** · Clean 58mm thermal layout. #### Simple Thermal Receipt (80mm) **Thermal · 80mm** · Clean 80mm thermal layout — most common. #### Simple Thermal Receipt 80mm (RTL) **Thermal · 80mm · RTL** · RTL counterpart for 80mm. Needs a printer with an Arabic codepage (CP864 / Windows-1256). #### Detailed Thermal Receipt (58mm) **Thermal · 58mm** · Kitchen-sink 58mm — addresses, tax breakdown, refunds, payments, terms, barcode. #### Detailed Thermal Receipt (80mm) **Thermal · 80mm** · Kitchen-sink 80mm — addresses, tax breakdown, refunds, payments, terms, barcode. #### Kitchen Ticket **Thermal** · Items only, large font, no pricing — for prep stations. ### Third-party document templates[​](#third-party-document-templates "Direct link to Third-party document templates") If **PDF Invoices & Packing Slips for WooCommerce** by WP Overnight is active, WCPOS also exposes **Invoice (WP Overnight)** and **Packing Slip (WP Overnight)** in the receipt template list. These server-rendered HTML templates delegate to WP Overnight's document API, reusing the invoice and packing-slip numbering, layout, branding, legal/tax fields, and template customisations configured in that plugin. They are available only while the WP Overnight plugin is active and require a server connection to render. Use WCPOS's bundled HTML or thermal templates when offline printing is required. ### Adaptive tax display[​](#adaptive-tax-display "Direct link to Adaptive tax display") Most bundled templates (Standard, Standard RTL, Minimal/Modern, Narrow, Invoice, Quote, Thermal Simple variants) **adapt automatically to your WooCommerce tax-display setting**: * **Tax-inclusive stores** (EU/UK/AU) see gross prices with a "Tax included" line. * **Tax-exclusive stores** (US/CA) see net prices with tax added as a separate line. * The grand total always shows the gross amount actually charged. The **Detailed** family is a formal tax invoice and always itemises tax with tax-exclusive lines plus an explicit breakdown, regardless of the store setting. ## How it works[​](#how-it-works "Direct link to How it works") 1. **Add a template** — click **Use Template** on a gallery card, or create your own from scratch. 2. **Customise it** using the in-app editor with live preview, or paste it into ChatGPT / Claude and ask for the changes you want. 3. **Activate it** — flip the **Active** toggle in *Your Templates*. Every active receipt template appears in the receipt-screen dropdown at the till. 4. **Print or display** — receipts open after checkout with options to print, email, or view on screen. Templates render against a standardised [receipt data payload](/receipts/receipt-data.md) with sections for store info, line items, totals, tax, payments, refunds, and more. Currency fields all include pre-formatted `_display` variants (e.g., `$29.99` instead of `29.99`). ## Pro features[​](#pro-features "Direct link to Pro features") With [WCPOS Pro](/getting-started/pro-license.md), each store can have its own template assignments, branding (logo, address, contact details), and template ordering — useful for multi-location operations where each shop prints its own letterhead. ## In this section[​](#in-this-section "Direct link to In this section") [Customise Your ReceiptThe easiest way to change how your WCPOS receipt looks — pick a different template, ask AI to tweak it, or edit it by hand.](/receipts/customise.md) [HTML TemplatesCreate and customise logicless HTML receipt templates using Mustache-style placeholders.](/receipts/html-templates.md) [Thermal TemplatesCreate XML-based receipt templates for ESC/POS thermal printers with Epson and Star support.](/receipts/thermal-templates.md) [Receipt DataComplete reference for the canonical data contract available in WCPOS receipt templates.](/receipts/receipt-data.md) [Cloud PrintingPrint WCPOS receipts to printers that aren't attached to the till — Star Online, Star CloudPRNT, Epson Server Direct Print, and PrintNode.](/receipts/cloud-printing.md) [ReceiptsPrint and email receipts in WCPOS, including printer setup and receipt customisation options.](/receipts/at-checkout.md) --- # Receipts After successfully processing a payment, the receipt modal displays. This shows a summary of the completed order and provides options to print or email the receipt. ## Receipt Contents[​](#receipt-contents "Direct link to Receipt Contents") The receipt displays: ### Store Information[​](#store-information "Direct link to Store Information") * **Store name** * **Address** * **Phone number** * **Email** * **Website** * **Logo** (if configured) ### Receipt Header[​](#receipt-header "Direct link to Receipt Header") * **Receipt type** (e.g., "Tax Receipt") * **Order number** * **Date and time** * **Cashier name** * **Payment method** ### Order Details[​](#order-details "Direct link to Order Details") * **Line items** with: * Product name * Variation attributes (if applicable) * Quantity * Price * Total ### Totals[​](#totals "Direct link to Totals") * **Subtotal** * **Tax** (if applicable) * **Total** * **Amount Tendered** (for cash) * **Change** (for cash) ### Customer Information[​](#customer-information "Direct link to Customer Information") * **Billing address** * **Shipping address** (if different) ## Receipt Actions[​](#receipt-actions "Direct link to Receipt Actions") ### Close[​](#close "Direct link to Close") Dismiss the receipt modal and return to the POS. ### Email Receipt[​](#email-receipt "Direct link to Email Receipt") Send the receipt to the customer's email address: 1. Click **Email Receipt** 2. Confirm the email address 3. The receipt is sent via WooCommerce's email system The customer must have an email address associated with the order. ### Print Receipt[​](#print-receipt "Direct link to Print Receipt") Print a physical copy of the receipt: 1. Click **Print Receipt** 2. Your browser's print dialogue opens 3. Select your receipt printer and print Receipt Printers WCPOS works with any printer accessible from your browser. For best results, use: * A dedicated receipt printer (thermal printers are common) * Configure paper size in your printer settings * Set up a print preset for quick printing ## Automatic Receipt Options[​](#automatic-receipt-options "Direct link to Automatic Receipt Options") In the [Cart Display Settings](/pos/cart/.md#display-settings), you can configure: * **Automatically show receipt after checkout** - Opens the receipt modal immediately after payment * **Automatically print receipt after checkout** - Triggers print automatically when receipt is shown These options speed up high-volume checkout workflows. ## Customising Receipts[​](#customising-receipts "Direct link to Customising Receipts") Receipt appearance is controlled by templates in WordPress: `WP Admin > POS > Templates` See [Receipt Templates](/receipts/.md) for details on customising: * Store information display * Logo and branding * Layout and formatting * What information to include ## Reprinting Receipts[​](#reprinting-receipts "Direct link to Reprinting Receipts") To reprint a receipt for a past order: 1. Go to the [Orders screen](/orders/.md) (Pro feature) 2. Find the order 3. Click to open the order 4. Use the receipt option to print again ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [Receipt TemplatesCustomise receipt appearance](/receipts/.md) [Cloud PrintingPrint to Star, Epson, and PrintNode printers](/receipts/cloud-printing.md) [Cart SettingsAuto-show and auto-print options](/pos/cart/.md#display-settings) [OrdersReprint past receipts (Pro)](/orders/.md) --- # Cloud Printing Cloud printing lets WCPOS send receipts to a printer that isn't directly connected to the device running the till. Set it up once in WP Admin and your orders print to a kitchen printer, a back-office printer, or a printer in another room — without each device having to discover and pair with the hardware itself. ## What is cloud printing?[​](#what-is-cloud-printing "Direct link to What is cloud printing?") With **local printing**, the device running the POS talks straight to the printer over USB, Bluetooth, or the local network. That's the right choice when the printer sits next to the till — see [Printer Setup](/hardware/printers.md) for connecting USB, Bluetooth, and network printers on the same device. **Cloud printing** is for everything else: a printer in a different location, on a different network, or one you want every device to share without configuring it on each one. There are two delivery models: * **Polling printers.** The printer reaches out to WCPOS over the internet on a schedule, asks "do you have anything for me?", and pulls down any waiting jobs. WCPOS never connects to the printer — the printer always starts the conversation. This is how **Star CloudPRNT** and **Epson Server Direct Print** work. * **Hosted relay providers.** WCPOS submits the print job to a hosted service, and that service delivers it to the printer. This is how **Star Online** and **PrintNode** work. Star Online delivers to Star CloudPRNT printers registered in your stario.online account; PrintNode delivers through its desktop client to almost any printer that computer can already print to. Why a printer that polls? A polling printer doesn't need an open port, a static IP, or any firewall changes — it only ever makes outbound requests. That makes it ideal for a printer at a remote site or behind a router you don't control. The trade-off is a short delay: the printer only prints when its next poll comes around. ## Choosing a provider[​](#providers "Direct link to Choosing a provider") Pick the provider that matches your hardware. #### Star CloudPRNT For Star thermal printers running the **CloudPRNT** firmware. The printer polls WCPOS and pulls jobs. Receipts are rendered to the printer's native commands. Needs a thermal template. #### Star Online For Star printers registered in a **stario.online** account. WCPOS submits Star Document Markup to Star's hosted service, and the printer collects it from Star Online. Needs a thermal template. #### Epson Server Direct Print For Epson ePOS printers that support **Server Direct Print**. The printer polls WCPOS and pulls jobs as ePOS-Print XML. Needs a thermal template. #### PrintNode Works with virtually any printer your computer can print to, on any OS, via the **PrintNode desktop client**. WCPOS submits a PDF, so you can use any template — including full-page HTML invoices. | Provider | Hardware | How jobs flow | Templates | | ----------------------------- | -------------------------------------------- | ------------------------------------------------- | ------------ | | **Star CloudPRNT** | Star thermal printer with CloudPRNT firmware | Printer polls WCPOS | Thermal only | | **Star Online** | Star printer registered in stario.online | WCPOS submits Star Document Markup to Star Online | Thermal only | | **Epson Server Direct Print** | Epson ePOS printer with Server Direct Print | Printer polls WCPOS | Thermal only | | **PrintNode** | Any OS-connected printer + PrintNode client | WCPOS submits a PDF to PrintNode | Any template | ## Setting up a cloud printer[​](#setup "Direct link to Setting up a cloud printer") Cloud printers are configured once in WP Admin and shared across every device — unlike local printers, which are stored per device. Go to **WP Admin > POS > Settings > Cloud Print** and click **Add printer**. Give it a **name** (for example "Kitchen" or "Back office"). WCPOS derives a stable **printer ID** from the printer automatically — it never changes, so it's safe to reference from a printer's firmware configuration. After the printer exists, configure the provider end. ### Star or Epson (polling printers)[​](#setup-polling "Direct link to Star or Epson (polling printers)") 1 #### Add the printer in WCPOS In **WP Admin > POS > Settings > Cloud Print**, add a printer and choose **Star CloudPRNT** or **Epson Server Direct Print** as the provider. WCPOS generates a **poll URL** and a **one-time token** for that printer. 2 #### Copy the poll URL and token Copy the generated poll URL and token. The **token is shown only once** — if you lose it, regenerate a new one from the printer card and update the printer with the new value. 3 #### Enter them in the printer's configuration Open the printer's configuration page — the **CloudPRNT** settings for Star, or the **Server Direct Print** settings for Epson — and paste in the poll URL and token. Set the poll interval if the printer asks for one (a few seconds is typical). Save and reboot the printer if required. Within a poll cycle the printer checks in, and its status in WCPOS changes from **Waiting** to **Connected**. ### PrintNode[​](#setup-printnode "Direct link to PrintNode") 1 #### Install the PrintNode desktop client On a computer that can already print to your target printer, install the **PrintNode client** and sign in. The client must stay running and online for jobs to print. 2 #### Get a PrintNode API key In your PrintNode account, create an **API key**. This is what lets WCPOS submit jobs to your PrintNode account. 3 #### Enter the API key in WCPOS Add a printer in **WP Admin > POS > Settings > Cloud Print**, choose **PrintNode** as the provider, and paste in the API key. WCPOS uses it to fetch the list of printers registered to your PrintNode account. 4 #### Select the printer Choose the target printer from the list of printers reported by the PrintNode client, then save. WCPOS will submit jobs for this printer to PrintNode, and the client prints them. ### Star Online[​](#setup-star-online "Direct link to Star Online") Use Star Online when your Star printer is already registered to a **stario.online** account and you want Star's hosted service to handle delivery. 1 #### Get the CloudPRNT URL In stario.online, open **Device Groups** and copy the group's **CloudPRNT URL**. It should look like `https://device.stario.online/cloudprnt/...` or `https://eu-device.stario.online/cloudprnt/...`. 2 #### Create an API key with permissions In stario.online, create an API key for WCPOS. The key must have permission to list devices and print to them. At minimum, enable: * **EnumDevices** — required when WCPOS fetches the device list * **ViewDevice** — used for device status checks * **PrintToDevice** — required to submit print jobs * **ViewDeviceGroups** — recommended for group lookup and diagnostics An API key can exist and still fail if these permissions are not enabled. 3 #### Enter the URL and API key in WCPOS Add a printer in **WP Admin > POS > Settings > Cloud Print**, choose **Star Online** as the provider, then paste the CloudPRNT URL and API key. Click **Fetch my devices**. 4 #### Select the Star device Choose the printer from the device list and save. WCPOS stores the API key server-side and uses the selected device's access identifier when submitting jobs to Star Online. ## Auto-print rules[​](#auto-print "Direct link to Auto-print rules") Auto-print rules decide what prints where, automatically — written as plain sentences. A rule is **scope × printer × template**, for example: > Print **every order** to **Kitchen** using **Kitchen Ticket**. When a matching order completes, WCPOS renders the chosen **template** server-side into the format the printer needs and queues it — there's nothing for the cashier to do. Template compatibility matters Star and Epson printers can only use **thermal** templates, because the job has to be rendered to the printer's native command language (Star Document Markup or ESC/POS for Star, ePOS-Print for Epson). PrintNode can use **any** template — thermal or full-page HTML — because the job is rendered to a **PDF**. If a template doesn't appear as an option for a printer, it's because the printer can't render that format. See [Thermal Templates](/receipts/thermal-templates.md) for creating thermal layouts. ## Per-store printers (Pro)[​](#per-store-printers "Direct link to Per-store printers (Pro)") Pro Feature Per-store print routing requires [WCPOS Pro](/getting-started/pro-license.md) and a [multi-store](/stores/.md) setup. By default, auto-print rules are global — every store shares them. With Pro, you can give an individual store its **own** cloud-print rules so its orders print to its own printers (a kitchen ticket at one location shouldn't print in another). Edit a store under **POS → Stores**, open its **Cloud Printing** section, and **Add rule**. Each rule is: * **Printer ID** — the stable ID of the cloud printer to send to * **Scope** — **POS orders only** (default), **Online orders only**, or **Every order** * **Format** — **StarPRNT** (default), **ESC/POS**, **Epson ePOS-Print**, or **HTML** When an order belongs to a store that has its own rules, WCPOS routes it to that store's printers. If a store has **no** rules of its own, it **falls back to the global** auto-print rules — so you only need to configure the stores that differ. ## Manual printing[​](#manual "Direct link to Manual printing") You don't have to wait for an auto-print rule. From the **checkout / receipt screen**, a cashier can send a receipt to a cloud printer on demand — handy for reprints or for routing a one-off ticket to a specific printer. How the receipt is produced depends on the printer: * **Star CloudPRNT** — the receipt is rendered **on the device** and handed to the printer through CloudPRNT. * **Star Online, Epson, and PrintNode** — the receipt is rendered **on the server** from the selected order and template, then delivered to the printer or hosted relay. ## Test print & connection status[​](#status "Direct link to Test print & connection status") Each printer card has a **Test print** button that sends a short diagnostic so you can confirm the printer is reachable and the format is right before relying on it for real orders. The card also shows a live status: | Provider | Status | Meaning | | -------------------------- | ------------- | ------------------------------------------------------------------------ | | **Star CloudPRNT / Epson** | **Waiting** | The printer hasn't checked in yet — WCPOS is waiting for its first poll. | | **Star CloudPRNT / Epson** | **Connected** | The printer polled WCPOS recently and is collecting jobs. | | **Star Online** | **Online** | Star Online reports the selected device is available. | | **Star Online** | **Offline** | Star Online reports the selected device is not available. | | **Star Online** | **Unknown** | WCPOS could not confirm the device status from Star Online. | | **PrintNode** | **Online** | The PrintNode service reports the client and printer are available. | | **PrintNode** | **Offline** | PrintNode reports the client or printer is unavailable. | ## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting") Printer stuck on Waiting A polling printer that never leaves **Waiting** has never successfully reached WCPOS. Check: * The **poll URL and token** in the printer's firmware exactly match what WCPOS generated. A single wrong character means every poll is rejected — regenerate the token in WCPOS and re-enter it if you're unsure. * The printer can actually **reach your site** over the internet (correct DNS, no firewall blocking outbound HTTPS, valid SSL certificate on your store). * **Polling is enabled** in the printer's CloudPRNT / Server Direct Print configuration, with a sensible interval. Reboot the printer after changing its settings. Star Online says the API key is unauthorised or forbidden Star Online separates **authentication** from **permissions**: * **401 / authentication failed** means the API key itself was not accepted. Check that the key was copied correctly, has not been revoked, and belongs to the expected Star Online account/region. * **403 / forbidden** means the API key was accepted but is not authorised for the requested action. Edit the key in stario.online and enable the required permissions, especially **EnumDevices** for **Fetch my devices** and **PrintToDevice** for printing. If **Fetch my devices** succeeds but no printers appear, check the stario.online **Device Groups** page. The group must contain at least one connected device, and the CloudPRNT URL in WCPOS must point to that same group. PrintNode job never prints The job reached PrintNode but didn't come out of the printer. Check: * The **PrintNode desktop client is running and online** on the computer connected to the printer. If the computer is asleep or the client is closed, nothing prints. * You selected the **correct printer** in WCPOS — the name must match the printer the client reports. * The **API key is valid** and hasn't been revoked. Re-enter it if PrintNode shows the printer as Offline. My template isn't selectable for a Star or Epson printer Only **thermal** templates work on Star and Epson cloud printers, because the receipt has to be rendered to ESC/POS or ePOS-Print commands. HTML and full-page templates can't be expressed in those formats, so they're hidden for these printers. Either choose a [thermal template](/receipts/thermal-templates.md), or use a **PrintNode** printer — PrintNode renders to PDF, so it can print any template. ## Related Documentation[​](#related-documentation "Direct link to Related Documentation") [Printer SetupConnect a printer on the same device or network](/hardware/printers.md) [TemplatesThe receipt template system](/receipts/.md) [Thermal TemplatesBuild ESC/POS layouts for Star and Epson printers](/receipts/thermal-templates.md) --- # Customise Your Receipt If you want to change how your receipt looks, you have three options. Pick the easiest one that does what you need — most stores never have to look past the first. ## Three ways to customise[​](#three-ways-to-customise "Direct link to Three ways to customise") #### 1. Pick a different template Use one of the ready-made templates in the gallery. **No code at all.** Best for: a different layout, hiding prices, an A4 invoice, a kitchen ticket. #### 2. Ask AI to tweak it Paste the template into ChatGPT or Claude and describe what you want. **No coding skills needed** — you describe it in plain English. Best for: small tweaks like wording, colours, or moving things around. #### 3. Edit it by hand The in-app editor lets you change the template directly. Best for: precise control, or if you already know HTML. All three start in the same place: **WP Admin → POS → Templates**. The page has two parts — **Your Templates** at the top (the ones you're using right now) and the **Template Gallery** below it (the starter library). ## Option 1 — Pick a different template[​](#option-1--pick-a-different-template "Direct link to Option 1 — Pick a different template") This is the easiest path and covers most needs. 1 #### Open the template gallery In WP Admin go to **POS → Templates**. Scroll past *Your Templates* to the **Template Gallery** section — that's the starter library. 2 #### Browse and preview Filter by **category** (Receipt, Invoice, Gift Receipt, Kitchen Ticket, Quote / Purchase Order), **format** (HTML for browser print, ESC/POS for thermal printers), or **direction** (Left-to-right or Right-to-left). Click any card's thumbnail — or the **Preview** link in its footer — to open a live preview with your store's real data. 3 #### Use it Click **Use Template** on the card. WCPOS makes you an editable copy and adds it to **Your Templates** at the top of the page. Flip the **Active** toggle on the row to start using it on receipts; drag the row's grip handle to reorder. You can have several active at once — the cashier picks at the till. Use Template never replaces anything Clicking **Use Template** always creates a fresh copy. The original gallery template is left untouched, so you can come back and pick a different starting point any time. If multiple receipt templates are active, the receipt screen shows a dropdown so the cashier can switch between them on the fly. ### The bundled templates[​](#the-bundled-templates "Direct link to The bundled templates") | Template | Format | What it's for | | ------------------------------------------ | ------- | ---------------------------------------------------------------------------- | | **Standard Receipt** | HTML | Default — logo, items, totals, payment. Covers most stores | | **Standard Receipt (RTL)** | HTML | Same as Standard, mirrored for Arabic / Hebrew / Persian / Urdu | | **Minimal / Modern** | HTML | Same info as Standard, packed into less vertical space | | **Detailed Receipt** | HTML | Full tax invoice — SKU column, unit price, per-rate tax breakdown, addresses | | **Gift Receipt** | HTML | Items only — prices hidden. Includes gift message and return policy | | **Invoice** | HTML | Full-page A4/Letter invoice. Adds a "How to pay" panel for unpaid orders | | **Packing Slip** | HTML | Warehouse companion — items + quantities, ship-to, no prices | | **Quote / Estimate** | HTML | Pre-sale document with pricing and terms — no payment section | | **Narrow Receipt** | HTML | Monospace receipt for narrow paper or HTML-capable thermal printers | | **Simple Thermal Receipt (58mm)** | Thermal | Clean 58mm thermal layout | | **Simple Thermal Receipt (80mm)** | Thermal | Clean 80mm thermal layout — most common | | **Simple Thermal Receipt 80mm (RTL)** | Thermal | RTL counterpart for 80mm. Requires a printer with an Arabic codepage | | **Detailed Thermal Receipt (58mm / 80mm)** | Thermal | Adds tax breakdown, addresses, refunds, payments, terms, barcode | | **Kitchen Ticket** | Thermal | Items only, large font, no prices — for prep stations | Most of the bundled templates **adapt to your store's tax settings automatically** — tax-inclusive stores see gross prices and a "Tax included" line; tax-exclusive stores see net prices with tax added as a separate line. The **Detailed** family always shows a full tax breakdown regardless of the setting. ### WP Overnight invoice and packing slip templates[​](#wp-overnight-invoice-and-packing-slip-templates "Direct link to WP Overnight invoice and packing slip templates") If your site also uses [PDF Invoices & Packing Slips for WooCommerce](https://wordpress.org/plugins/woocommerce-pdf-invoices-packing-slips/) by WP Overnight, WCPOS automatically adds two extra templates to **Your Templates**: | Template | Format | What it's for | | ------------------------------- | -------------------- | ---------------------------------------------------------------------- | | **Invoice (WP Overnight)** | Server-rendered HTML | Uses WP Overnight's configured invoice document for the POS order | | **Packing Slip (WP Overnight)** | Server-rendered HTML | Uses WP Overnight's configured packing-slip document for the POS order | These templates do not copy WCPOS's built-in invoice or packing-slip layouts. They ask WP Overnight to render the document for the POS order, so your existing invoice numbers, branding, legal/tax fields, and WP Overnight template customisations stay consistent between online and in-store orders. They appear only while the WP Overnight plugin is active. The output opens as HTML in the WCPOS print screen rather than as a separate PDF download. Because the document is rendered on the server, the POS needs a connection to your site when printing these templates; use the bundled HTML or thermal templates for offline printing. ## Per-store assignments[​](#per-store-assignments "Direct link to Per-store assignments") If you have more than one [store](/stores/.md) (Pro), each store can have its **own template selection and ordering**, separate from the site-wide defaults. The cafe down the road can run a small thermal receipt with a different logo and address; the warehouse can use a packing slip; the main shop can keep the standard receipt — all from the same template gallery. Set it up from **WP Admin → POS → Stores**, then open the store you want to configure. The **Edit Store** page has a **Receipt Templates** section with a *"Store specific receipt templates"* toggle: * **Toggle off** *(default)* — the store inherits the site-wide template list from the main **POS → Templates** page. * **Toggle on** — the store gets its own template selection and ordering, separate from the site-wide defaults. Drag-handle reorder works the same way. The same Edit Store page is also where each store's **letterhead** lives (logo, address, contact details, and the *Receipt Messages* block — Complimentary Close, Returns Policy, Footer). The bundled templates pull from these per-store fields, so a single "Standard Receipt" template can carry different branding at different locations. When a cashier signs in at a store, only that store's active templates appear in the receipt dropdown. Site-wide vs per-store The **Templates** page in WP Admin sets the default for the whole site. The per-store override exists so a single template (e.g. a Standard Receipt) can carry different branding at different locations, or so one location can use a layout the others don't. If all your stores want the same templates, just leave per-store assignments empty and the site-wide defaults apply. ## Option 2 — Ask AI to tweak it[​](#option-2--ask-ai-to-tweak-it "Direct link to Option 2 — Ask AI to tweak it") If the gallery is close but not quite right, an AI assistant can change it for you in minutes — and you don't need to know HTML. 1 #### Copy the template Open the template you want to start from in **WP Admin → POS → Templates**, click into the editor, and select all of the text on the left side (Ctrl/Cmd + A). Copy it. 2 #### Paste it into ChatGPT or Claude Open [ChatGPT](https://chat.openai.com) or [Claude](https://claude.ai). Paste the template, then write what you want, in plain English: 3 #### Describe what to change Tell the AI exactly what you want. Examples that work well: * *"Make the store name bigger and centered."* * *"Add a thank-you message in italic at the bottom."* * *"Hide the customer name. Add the phone number underneath the order number instead."* * *"Change the barcode to a QR code that links to my returns page."* * *"Add a tagline 'Family-owned since 1987' under the store name."* The AI will hand you back a modified template. 4 #### Paste it back Copy the AI's response. Back in the WCPOS template editor, select all (Ctrl/Cmd + A), paste the new version, and click **Update**. The preview on the right refreshes so you can see what happened. If it doesn't look right, ask the AI to fix it — describe what went wrong. Best practice Every click of **Use Template** in the gallery makes a fresh editable copy, so the original stays safe. If you're experimenting, you can use the same gallery template more than once — rename your copies *(Receipt v1, Receipt v2)* and toggle between them while you decide. What about variables? The bits like `{{store.name}}` and `{{order.number}}` are **placeholders** for your real data. The AI understands these — you don't need to. If you want to know every placeholder available, see the [Receipt Data Reference](/receipts/receipt-data.md). ## Option 3 — Edit it by hand[​](#option-3--edit-it-by-hand "Direct link to Option 3 — Edit it by hand") If you know a bit of HTML (or you're working with a developer), you can edit the template directly in the in-app editor. The editor has live preview, syntax highlighting, a searchable field picker, undo/redo, and find-and-replace. Choose your engine: * **[HTML Templates](/receipts/html-templates.md)** — Mustache-style `{{variable}}` placeholders. Renders client-side, works offline. **Recommended for most stores.** * **[Thermal Templates](/receipts/thermal-templates.md)** — XML for ESC/POS thermal printers. Same template produces both the screen preview and the printer output. * **[Receipt Data Reference](/receipts/receipt-data.md)** — Every placeholder you can use, grouped by section. Legacy PHP templates If you used to override the receipt with a PHP file in your theme (`yourtheme/woocommerce-pos/receipt.php`), that still works. It's now labelled **Legacy PHP Template** in the gallery, and it sits alongside the new logicless and thermal engines. The WP Overnight integration also uses the server-rendered path because the third-party document API renders HTML on the server. New customisations should use the gallery or the in-app editor instead — they work offline, preview live, and don't need a server round-trip. ## Common customisations[​](#common-customisations "Direct link to Common customisations") Quick answers to the questions we get most often. How do I add my store logo? Logos come from your store settings, not the template itself. Go to **WP Admin > POS > Settings > Stores**, edit your store, and upload a logo there. Every bundled template that shows a logo will use it automatically. If you want to change *where* the logo appears in the template, edit the template and move the `{{#store.logo}}{{/store.logo}}` block to where you want it. How do I change the footer text (e.g. 'Thank you for your purchase!')? Two options: 1. **Easiest** — set it once for every receipt at **WP Admin > POS > Settings > Stores > Store details > Receipt footer / personal note**. Bundled templates pick it up automatically; if no footer is set, they fall back to a friendly default like *"Thank you for your purchase!"*. 2. **In a single template** — edit the template and replace the footer text directly. Look for `{{store.personal_notes}}` or the literal thank-you line. How do I add a tagline or slogan under the store name? Edit the template and add a line under `{{store.name}}`: ```
Family-owned since 1987
``` In a thermal template: ``` Family-owned since 1987 ``` How do I hide prices (for a gift receipt)? Click **Use Template** on the **Gift Receipt** card in the gallery — it hides every price and total while still showing items, SKU, attributes, and the gift message. No editing required. If you'd rather build your own price-free receipt, copy any template and delete the `{{...total...}}`, `{{...price...}}` and `{{#totals}}...{{/totals}}` blocks. How do I change the barcode to a QR code? Find the `` element in your template and change the `type` attribute: ``` {{order.number}} {{order.number}} https://example.com/returns?order={{order.number}} ``` The same `` syntax works in both HTML and thermal templates. Other supported types include `ean13`, `ean8`, `upca`, `pdf417`, and [everything bwip-js supports](https://github.com/metafloor/bwip-js/wiki/Supported-Barcode-Types). How do I send a different template to a specific printer? In the POS app, go to **POS > Settings > Printing**, then look under **Receipt templates**. You'll see each of your active templates with a printer dropdown next to it. Pick the printer you want, or leave it as **Auto**. * **Auto** matches templates to printers automatically — thermal templates go to thermal printers, HTML templates go to the system print dialog. * A **specific printer** overrides Auto and always sends that template there. * At print time, the cashier can override either of the above with the printer dropdown on the receipt screen. Routing is stored per-device, so each iPad or computer can have its own setup. My receipt still shows the old version after I edit it Click the WordPress **Update** button on the template edit screen. The editor doesn't auto-save — your changes only persist when you Update. For **Legacy PHP templates**, the preview in the editor shows the *last saved* version, not what you're typing. Save first, then refresh the preview. The preview is blank or shows 'No POS orders found' This only happens with **Legacy PHP templates**, which need a real order to preview against. Process a single POS order — even a $0 test sale — and the preview will start working. Logicless (HTML) and thermal templates always have sample data to fall back on, so they preview fine even on a brand-new store. I made a mess — how do I start over? Three safety nets: 1. The editor has **Undo** (Ctrl/Cmd + Z) for in-session changes. 2. Every save creates a WordPress **revision** — open **Revisions** on the edit screen to compare and restore any prior version. 3. If you started from a gallery template, click **Delete** on your copy in *Your Templates*, then click **Use Template** on the same gallery card again. You get a fresh, untouched copy. ## When to ask for help[​](#when-to-ask-for-help "Direct link to When to ask for help") * The template editor won't load, or saves don't stick. * The receipt prints fine on one device but not another. * You need a fiscal/legal layout for a specific country (Italy, Brazil, Spain, etc.) — these are usually handled by [WCPOS Pro](/getting-started/pro-license.md) or a country-specific integration. * You're trying to do something custom and AI can't quite get it right. Open a [support ticket](https://wcpos.com/support) and paste the template you're working with — that gives us everything we need to help. --- # HTML Templates HTML templates use a logicless Mustache-style syntax with `{{variable}}` placeholders. They render client-side in the POS app, which means they **work offline** — no server connection needed to display or print a receipt. This is the recommended engine for most users. ## Syntax[​](#syntax "Direct link to Syntax") ### Variables[​](#variables "Direct link to Variables") Insert data using double curly braces: ```

{{store.name}}

Order #{{order.number}}

Total: {{totals.total_display}}

``` Use `_display` variants for pre-formatted currency values (e.g., `$12.50` instead of `12.5`). See the [Receipt Data Reference](/receipts/receipt-data.md) for all available fields. ### Sections (Loops and Conditionals)[​](#sections-loops-and-conditionals "Direct link to Sections (Loops and Conditionals)") Use `{{#section}}...{{/section}}` to loop over arrays or conditionally show content: ``` {{#lines}}
{{name}} × {{qty}} {{line_total_display}}
{{/lines}} ``` ### Inverted Sections[​](#inverted-sections "Direct link to Inverted Sections") Use `{{^section}}...{{/section}}` to show content when a value is empty or false: ``` {{#customer.id}}

Customer: {{customer.name}}

{{/customer.id}} {{^customer.id}}

Guest checkout

{{/customer.id}} ``` ### Localised Labels[​](#localised-labels "Direct link to Localised Labels") Use `{{i18n.key}}` for translatable labels that adapt to the store's language: ``` {{i18n.subtotal}} {{totals.subtotal_display}} ``` ## Common Patterns[​](#common-patterns "Direct link to Common Patterns") ### Store Header[​](#store-header "Direct link to Store Header") The `store.address_lines` array is pre-formatted for receipts — loop it instead of stitching individual address fields together. ```
{{#store.logo}}{{store.name}}{{/store.logo}}

{{store.name}}

{{#store.address_lines}}
{{.}}
{{/store.address_lines}} {{#store.phone}}
{{store.phone}}
{{/store.phone}} {{#store.tax_ids}}
{{#label}}{{label}} {{/label}}{{value}}
{{/store.tax_ids}}
``` ### Line Items with Discounts[​](#line-items-with-discounts "Direct link to Line Items with Discounts") A line item's `discounts` field is the discount amount as a positive number, or `0` when there's no discount. Mustache treats `0` as falsy, so `{{#discounts}}...{{/discounts}}` is the right guard. ``` {{#lines}}
{{name}} × {{qty}}
{{#discounts}}
{{unit_subtotal_display}} {{unit_price_display}}
{{/discounts}}
{{line_total_display}}
{{/lines}} ``` ### Tax Summary[​](#tax-summary "Direct link to Tax Summary") ``` {{#tax_summary}}
{{label}} ({{rate}}%) {{tax_amount_display}}
{{/tax_summary}} ``` ### Payment Details[​](#payment-details "Direct link to Payment Details") ``` {{#payments}}
{{method_title}} {{amount_display}}
{{#tendered}}
{{i18n.tendered}}{{tendered_display}}
{{i18n.change}}{{change_display}}
{{/tendered}} {{/payments}} ``` ### Barcodes and QR Codes[​](#barcodes-and-qr-codes "Direct link to Barcodes and QR Codes") Use the `` element — the same syntax as [thermal templates](/receipts/thermal-templates.md). The value goes inside the element; the symbology is set on the `type` attribute. The renderer replaces each element with an inline SVG. ``` {{order.number}} {{order.payment_url}} {{order.number}} ``` The `type` attribute must be set **literally** in the template — it can't come from a placeholder. A `type` of `qr` or `qrcode` renders as a QR code in both HTML and thermal templates. If the selected barcode type can't encode the value (for example non-numeric or wrong-length EAN-13 data), the preview shows a `Barcode error` or `QR code error` block with the original value, so you can fix the value or switch to a compatible type. All [bwip-js symbologies](https://github.com/metafloor/bwip-js/wiki/Supported-Barcode-Types) are supported — `code128`, `qrcode`, `ean13`, `ean8`, `upca`, `pdf417`, `datamatrix`, and many more. ## Styling[​](#styling "Direct link to Styling") Logicless templates are sanitised through WordPress's `wp_kses_post` before rendering, which **strips `