This page covers setup and usage for Lightspeed Retail X-Series (added in v3.0.0). If you’re on R-Series, see R-Series setup and usage →. For installation steps, see the overview page →
Connect to Lightspeed X-Series
↑ Back to top- Go to Lightspeed > Connection.
- Select X-Series from the series dropdown.
- Click Connect to Lightspeed X-Series.
- Authorize the connection when redirected to Lightspeed.
- After redirecting back to your site, the Connection page shows a “Connected (not ready)” status.
- Click Configure the plugin to continue setup.
The connection is established, but the plugin cannot sync until you select an outlet and register.
Select an outlet register
↑ Back to topAfter connecting, go to Lightspeed > Settings > General and select your Outlet register from the dropdown.
The outlet register determines:
- Which Lightspeed outlet’s inventory is matched to WooCommerce stock levels
- Which register WooCommerce sales are attributed to in Lightspeed (when order sync is enabled)
We recommend creating a register in Lightspeed specifically for your WooCommerce store before completing this step. If the dropdown is empty, it means no registers are configured in Lightspeed — go to your Lightspeed outlets and registers dashboard and create one, then reload this page.
Once the register is chosen and saved, it cannot be changed without disconnecting and reconnecting.
After selecting a register and saving, the Connection page status updates to “Connected (ready)” and syncing can begin.
Enable stock management
↑ Back to topGo to WooCommerce > Settings > Products > Inventory and enable Enable stock management. This lets WooCommerce track stock levels and lets the plugin know when to push inventory changes back to Lightspeed.
Settings
↑ Back to topX-Series settings are organized under Lightspeed > Settings with five tabs: General, Products, Customers, Orders, and Background polling.
General tab
↑ Back to top- Outlet register — select your outlet and register (required before syncing)
- Staging mode — only appears when the plugin detects a staging environment. Toggle controls whether sync operations are allowed on the staging site. Enabled by default. Disable this on staging sites where you don’t want changes pushed to your live Lightspeed account.
- Debug mode — enable to generate detailed logs under WooCommerce > Status > Logs
Products tab
↑ Back to topChanges in WooCommerce
Controls whether WooCommerce product edits push back to Lightspeed:
- Update products in Lightspeed on-demand only (default) — changes only push during a manual sync from the Sync screen
- Update products in Lightspeed automatically — changes push to Lightspeed whenever a product is created or updated in WooCommerce
Match products by
How the plugin links WooCommerce products to their Lightspeed counterparts:
- SKU (default) — matches on product SKU
- GUID — matches on the product’s global unique identifier
Products without a value for the chosen field can’t be linked. If no match is found on import, the plugin creates a new product in Lightspeed instead.
Sync product SKUs
Enabled by default. Keeps WooCommerce and Lightspeed SKUs in sync. SKUs must be unique across both platforms — a conflict will cause a sync error.
Map product SKUs to
Choose which Lightspeed product code field WooCommerce SKUs are written to (Custom SKU, EAN, UPC, etc.).
Sync product GUIDs
Enabled by default. Keeps WooCommerce product GUIDs in sync with a Lightspeed product code. GUIDs must be unique.
Map product GUIDs to
Choose which Lightspeed product code field WooCommerce GUIDs are written to. Defaults to EAN.
WooCommerce supports one numeric product code (other than SKU). Lightspeed products can have multiple. If a product in Lightspeed has multiple product codes, only the mapped field is synced.
Product categories
- Do not import product categories from Lightspeed — categories are ignored entirely
- Replace WooCommerce categories upon sync (default) — Lightspeed categories replace WooCommerce categories on each sync
- Add missing categories from Lightspeed upon sync — new Lightspeed categories are added without removing existing WooCommerce categories
Categories are matched by name. Category hierarchy from Lightspeed is not imported, but you can adjust the hierarchy in WooCommerce after import.
Products with no assigned category in Lightspeed are imported under “Uncategorized” in WooCommerce. Categories deleted in Lightspeed are not removed from WooCommerce products.
Tags
Product tags are not synced from Lightspeed.
Customers tab
↑ Back to topChanges in WooCommerce
Controls whether WooCommerce customer changes push to Lightspeed:
- Update customers in Lightspeed on-demand only (default) — changes only push during a manual sync
- Update customers in Lightspeed automatically — changes push to Lightspeed when customers are created or updated in WooCommerce
The background polling job monitors Lightspeed for customer changes and updates WooCommerce on the configured interval. Configure this under the Background polling tab.
Orders tab
↑ Back to topSync orders
Disabled by default. When enabled, WooCommerce orders are automatically sent to Lightspeed as sales when created or updated. Only orders containing products that are synced to Lightspeed are transmitted. Deleted or trashed orders cannot be removed in Lightspeed.
Tax rates
Enabling order sync requires that WooCommerce tax rates be synced into Lightspeed. The plugin handles this automatically, creating matching tax rates in Lightspeed. Two important notes:
- Do not modify or delete the tax rates the plugin creates in Lightspeed — this will cause sync errors
- Compounding tax rates are not supported
Background polling tab
↑ Back to topFour background jobs run on a configurable interval. Set them to staggered intervals to avoid running all at the same time.
| Job | Default interval | What it does |
|---|---|---|
| Products | Every 10 minutes | Checks Lightspeed for product changes and updates WooCommerce |
| Customers | Every 20 minutes | Checks Lightspeed for customer changes and updates WooCommerce |
| Product images | Every 1 minute | Downloads updated product images from Lightspeed asynchronously |
| Token refresh | Every 50 minutes | Refreshes the Lightspeed API access token automatically |
Each can be set to intervals from 1 minute to 1 hour, or disabled entirely. Setting them too frequent on a resource-constrained server can cause API rate limit errors — if that happens, increase the interval.
Product images from WooCommerce are never pushed back to Lightspeed.
When a manual background sync (Pull or Push) is in progress, polling for the corresponding item type pauses automatically until the manual sync completes or is cancelled.
Sync screen
↑ Back to topGo to Lightspeed > Sync to manage manual syncs and view activity. The Sync screen has three tabs: Products, Customers, and Orders.
Products tab
↑ Back to topShows the current sync state of your product catalog. From here you can:
- Pull products from Lightspeed — import all Lightspeed products into WooCommerce in a background job
- Push products to Lightspeed — send WooCommerce product data back to Lightspeed in a background job
- View the activity log for recent product sync events
Background sync jobs can be large operations. The plugin processes them in batches (50 products per batch by default). If a background sync is in progress and you need to stop it, use the cancel button. You can resume or start over from the same screen.
When you pull products, the plugin automatically links any existing WooCommerce product that shares a SKU with a Lightspeed product. No duplicate is created. Product images download asynchronously via the product images background job — they may not appear immediately after the sync completes.
Take a database backup before running your first pull on a large catalog.
Deleting a product in Lightspeed does not automatically remove it from WooCommerce. Delete it manually in WooCommerce if you no longer want it listed.
Product actions after sync
On any synced product’s edit page, the Lightspeed Settings metabox in the sidebar provides these actions:
| Action | What it does |
|---|---|
| View Activity | Shows the sync activity log for this product |
| Open in Lightspeed | Opens the product directly in your Lightspeed dashboard |
| Disconnect from Lightspeed | Removes the sync link for this product without deleting it |
| Sync with Lightspeed | Manually triggers a sync for this product |
Customers tab
↑ Back to topManage customer sync between WooCommerce and Lightspeed:
- Pull customers from Lightspeed — import Lightspeed customers into WooCommerce
- Push customers to Lightspeed — send WooCommerce customers to Lightspeed
- View the activity log for recent customer sync events
Orders tab
↑ Back to topView the status of WooCommerce orders that have been sent to Lightspeed. Orders sync automatically when created or updated (if order sync is enabled in Settings > Orders tab). The activity log shows which orders synced, when, and whether any errors occurred.
Variable products
↑ Back to topIn Lightspeed X-Series, products with variants are equivalent to WooCommerce variable products. On import, WooCommerce creates the parent product and all variations with their respective inventory, pricing, and SKUs.
Inventory changes on any variation push to Lightspeed. The background products poller picks up changes from Lightspeed and updates WooCommerce on the configured interval.
Real-time inventory checks at cart and checkout
↑ Back to topThe plugin checks inventory against Lightspeed at two points in the purchase flow:
- Add to cart — when a customer adds a product to their cart, the plugin queries Lightspeed for the current stock level and updates WooCommerce before allowing the add. If the item is out of stock in Lightspeed, the add-to-cart is blocked.
- Before checkout — before the order is processed, all products in the cart are re-checked against Lightspeed. This catches any stock that changed between add-to-cart and checkout submission.
These checks run in addition to the background polling sync. They protect against oversells even when the scheduled sync interval hasn’t run recently — for example, if a product sold in-store between polling cycles.
This behavior applies to all products with stock management enabled in WooCommerce. It cannot be disabled per-product.
Disconnecting
↑ Back to topIf you need to reconnect or change your outlet register, disconnect from the Connection page. Disconnecting clears all connection data and forgets which Lightspeed products and customers correspond to your WooCommerce records. Imported products and customers in WooCommerce are not deleted, but the plugin will no longer know how to match them to Lightspeed until you sync again.
If you’re experiencing authentication issues but don’t want to lose your link data, use the Reconnect option instead of Disconnect.
Troubleshooting
↑ Back to topCannot connect to Lightspeed
↑ Back to topAfter connecting, the status shows “Connected (not ready)” until you select an outlet register under Lightspeed > Settings > General. This is expected — select a register and save to complete setup.
Products are not syncing
↑ Back to topIf a background sync is in progress, polling for that item type is paused automatically. Check the Sync screen to see if a background job is running.
Getting 429 “Rate Limit Exceeded” errors
↑ Back to topIncrease your background polling intervals under Settings > Background polling.
Images are missing after import
↑ Back to topImage downloads run asynchronously via the product images poller. If images haven’t appeared, check that the product images poller is enabled and running under Settings > Background polling.
Variable products not syncing correctly
↑ Back to topCheck the Sync screen activity log for errors. Verify SKU or GUID values are consistent between platforms (depending on your “Match products by” setting).
A product is linked but not updating
↑ Back to topPull the product again from the Sync screen. The plugin will match on SKU or GUID (based on your match setting) and re-establish the link.
Duplicate product ID or SKU error
↑ Back to topVerify the “Match products by” setting and that the chosen field has unique values across all products in both systems.
FAQ
↑ Back to topHow is pricing synced?
↑ Back to topRegular and sale prices are pulled from Lightspeed on each product sync.
Do WooCommerce orders sync to Lightspeed?
↑ Back to topYes, but order sync is disabled by default. Enable it under Settings > Orders. When enabled, orders sync to Lightspeed with tax rate data. Only orders containing synced products are transmitted.
Does X-Series support customer sync?
↑ Back to topYes. X-Series supports bidirectional customer sync. You can pull customers from Lightspeed into WooCommerce, push WooCommerce customers to Lightspeed, and configure automatic sync when customers are created or updated.
Can I disconnect without losing my product data?
↑ Back to topDisconnecting clears connection data and forgets which Lightspeed products and customers correspond to your WooCommerce records. Your imported WooCommerce products and customers are not deleted, but the plugin won’t know how to match them to Lightspeed until you sync again. If you’re only having authentication issues, use Reconnect instead.
