Fixes for the problems Lightspeed Retail X-Series stores run into most: connections that don’t complete, products or stock that don’t sync, and orders that don’t reach Lightspeed. Each issue starts with what you see and quotes the plugin’s messages, so you can search for the one in front of you.
For R-Series, see Troubleshoot Lightspeed R-Series.
When you’d use this
- A connection, product, customer or order doesn’t sync the way you expect.
- You see an error message from the plugin or from Lightspeed.
- You’re collecting details before contacting support.
Find out what happened
Start with the plugin’s own records before changing settings:
- The activity log. Lightspeed » Sync lists every product, customer and order sync with its status. Open an event’s details to see what was sent and Lightspeed’s response. Each product’s Lightspeed sync box links to its own activity with View activity.
- Order notes. Every order sync adds a note saying whether it worked, with the reason when it didn’t.
- The log. Turn on Debug mode under Lightspeed » Settings » General, repeat the action, then open WooCommerce » Status » Logs and pick the
kestrel-lightspeed-poslog. Lightspeed’s full error is only logged while Debug mode is on. Turn it off afterward. - Scheduled jobs. Background polling runs through Tools » Scheduled Actions. Search for
lightspeedand look for failed or long-pending actions.
Lightspeed is the source of truth for products and stock. If WooCommerce and Lightspeed disagree, fix the data in Lightspeed and let it sync, rather than editing WooCommerce.
Connection
Can’t connect, or the connection doesn’t complete
Work through these:
- Bot protection or a firewall. Cloudflare’s Bot Fight Mode and similar bot challenges can block the connection’s return trip to your site, so authorizing seems to hang or fail. Allow the connection’s requests through, or pause the protection while you connect.
- Your Lightspeed plan. The connection uses Lightspeed’s API. On Lightspeed’s current plans, API access comes with the Plus plan; some older plans include it. Check your plan or ask your Lightspeed account manager.
- The browser. Try a private window, and make sure a security plugin isn’t blocking the redirect back to Lightspeed » Connection.
The Connection screen reports what went wrong under "There were errors while trying to connect to Lightspeed POS:", for example:
- "Successfully initiated connection to Lightspeed POS, but the connection was not completed. Please try again or check the logs."
- "Authorization with Lightspeed failed." followed by Lightspeed’s reason.
- "An error occurred during authentication. Please try again or contact support."
"Connected (not ready)"
You’re connected but haven’t saved a register. Choose an Outlet register under Lightspeed » Settings » General and click Save changes. On a staging site the status also stays not ready while Staging mode is off.
"A staging website has been detected. Sync operations with Lightspeed servers are currently disabled."
The plugin thinks this is a staging site and Allow sync operations on staging website is turned off. That’s what you want on a staging copy. If this is your live store, turn the setting on under Lightspeed » Settings » General.
A connection that worked has stopped
The connection’s access was revoked or expired. Messages include "Could not connect with Lightspeed." and the order note "Lightspeed connection expired or unauthorized — reconnect from the Lightspeed settings." Go to Lightspeed » Connection and click Reconnect to Lightspeed X-Series. Reconnecting keeps your product and customer links; don’t use Disconnect, which forgets them.
"The register saved here no longer exists in Lightspeed."
The register was deleted or renamed out of the outlet in Lightspeed. Choose an available register and save. If it’s in another outlet, click Reset register first.
Products and stock
Changes in Lightspeed don’t show up in WooCommerce
- Check that the Products interval under Lightspeed » Settings » Background polling isn’t Do not automatically sync in background.
- Check Lightspeed » Sync for a running import or export. While one runs, polling pauses, and the Background polling tab says so ("A background sync is in progress. Products and customers polling is paused while a manual sync is in progress.").
- Make sure WP-Cron runs. On a low-traffic site, or with
DISABLE_WP_CRONset and no real cron job, scheduled syncs run late or not at all. - To update one product now, open it and click Re-sync from Lightspeed. For several, use the Re-sync from Lightspeed bulk action on the Products list.
My stock changes in WooCommerce keep reverting
Lightspeed overwrites WooCommerce stock on every update, and the add to cart check pulls it again too. Change stock in Lightspeed. If another plugin, such as an inventory manager or bulk editor, writes stock to synced products, stop it from doing so.
Stock doesn’t match between WooCommerce and Lightspeed
- Stock comes from the outlet of your chosen register only. Stock in other outlets isn’t counted.
- A product that doesn’t track inventory in Lightspeed has Manage stock? turned off in WooCommerce.
- Something on the WooCommerce side may be writing stock (see the previous issue).
Correct the count in Lightspeed and re-sync the product.
A product won’t link, or a new duplicate was created
Products link by the Lightspeed product code mapped to the SKU (Custom SKU by default) or the global unique identifier. Check that both sides have the same, unique value, and that Map product SKUs to points at the Lightspeed field you use. To link one product, enter the matching SKU and click Connect to Lightspeed in its Lightspeed sync box. Delete duplicates you don’t need in WooCommerce.
"Cannot create or update a product in Lightspeed without a valid SKU."
The product has no SKU (or no global unique identifier, if Match products by is GUID). Add one and try again.
A sync fails with a duplicate SKU or product code
SKUs and product codes must be unique on both sides. Find the other product using the value, in WooCommerce or Lightspeed, and change one of them.
Setting a product to Draft removed it from my Lightspeed register
Whenever a product goes to Lightspeed, including the stock update after an order or a stock edit, a Draft, Pending or Private product is made inactive there. To hide a product online only, keep it Published and set Catalog visibility to Hidden. Then make it active again in Lightspeed.
A product went to Draft by itself
It’s inactive in Lightspeed, or it has a tag listed in Exclude by tags. Reactivate it or remove the tag in Lightspeed, and the next update publishes it.
Images are missing
Images download after the product, in batches, through the Product images polling job. Check that it isn’t turned off under Background polling (turning it off stops image import), and see the pending count on Lightspeed » Sync » Products. Failed downloads are retried. Images never go from WooCommerce to Lightspeed.
Some variations are missing or out of date
Check the product’s activity for errors, and that each Lightspeed variant has a unique SKU. Then click Re-sync from Lightspeed on the variable product.
"API rate limit exceeded", or syncs are slow
Lightspeed limits how many requests the plugin can make, and the plugin slows itself down as it nears the limit. If you still see 429 errors, raise the intervals under Background polling and keep them different from each other, avoid exporting large catalogs while polling runs, and let big imports finish.
An import or export seems stuck
Open the tab on Lightspeed » Sync and click Cancel sync in the progress notice. Items already synced stay. Start it again with Resume, or Start over to re-sync everything. Imports and exports run as background requests to your own site, so a host that blocks loopback requests stops them; see Get started with Lightspeed POS.
Customers
Some Lightspeed customers didn’t import
Customers are matched and created by email address. Customers without a valid email in Lightspeed are skipped, and the activity log shows "A WooCommerce customer with the email … already exists and cannot be created." when a different account already uses the email.
Orders
An order didn’t sync to Lightspeed
- Check that Sync orders is on under Lightspeed » Settings » Orders.
- Check that every product in the order is linked to Lightspeed. Orders with an unlinked product aren’t sent, and get no note.
- Read the order notes for "Lightspeed sync failed:" and the reason.
- After fixing the cause, change the order’s status to sync it again.
See Sync orders to Lightspeed X-Series for what order sync sends.
Lightspeed rejects the sale as out of balance
When Record payments as is set, the plugin sends one payment equal to the sale lines it sent: for each product, quantity × (price + tax), minus the line’s discount. Shipping and fees aren’t sale lines, so they’re not in the payment either. Lightspeed recalculates the sale itself, and refuses it when its total and the payment differ.
- Turn on Debug mode and sync the order again (change its status) to log Lightspeed’s full error.
- Check that the products’ tax rates match between WooCommerce and Lightspeed, and that you haven’t edited the taxes the plugin created in Lightspeed.
- Check that the payment type chosen in Record payments as still exists in Lightspeed.
- As a workaround, set Record payments as back to Do not record payments. Sales then sync without a payment, so they aren’t marked paid or closed in Lightspeed.
- Contact support with the logged error.
"To record payments, the plugin needs permission to list your Lightspeed payment types."
Your connection was authorized before the plugin asked for payment type access. Go to Lightspeed » Connection, click Reconnect to Lightspeed X-Series, then choose a payment type on the Orders tab.
"Compound tax rates are not supported for syncing orders to Lightspeed."
Replace the compound rate with an ordinary rate under WooCommerce » Settings » Tax, then sync the order again.
"Lightspeed sync failed: … Retrying at …"
Lightspeed was busy or unavailable. The plugin retries on its own for up to an hour; nothing to do unless the last note says it failed.
"Product stock was sent to Lightspeed directly because the sale could not be synced."
The sale failed for good, so the plugin updated the products’ stock in Lightspeed instead. Fix the reason in the previous note. If you then sync the order again by changing its status, the new sale deducts the stock in Lightspeed a second time, so check those products’ stock in Lightspeed afterward.