top of page
bg blob.png

Documentation

Payment Receipt
Woocommerce Lightspeed Integration

WooCommerce Lightspeed Integration Documentation 

WooCommerce Lightspeed POS allows you to integrate and import inventory from Lightspeed to WooCommerce and sync inventory across both systems.

​

We continue to add features and improve our customers' experience. Contact Us with any presale questions or feature requests. We’d love to hear from you.

​

Version history

woocommerce-lightspeed-header.jpeg

​This extension requires a Lightspeed Retail account. If you do not have one, you can sign up for a free Lightspeed trial account here.

Installation

  1. Download the .zip file from your WooCommerce.com account.

  2. Go to: WordPress Admin > Plugins > Add New to upload the file you downloaded with Choose File.

  3. Activate the extension.
     

More information at: Installing and Managing Plugins.

Concept

Before we get started, here is a little theory to help you understand what kind of sync relationship this extension establishes.
 

The sync scenario:

It is helpful to know the difference between a 1-way and 2-way sync scenario. This extension sets up a 1-way sync scenario. What does that entail? Here is a rough concept draft of it:

​

Initial Setup 1-way sync (available)

  • WooCommerce is empty, no products.

  • Lightspeed is full, many products.

  • Lightspeed fills WooCommerce with products. Initial Import (See next: Load Products from Lightspeed POS).

  • WooCommerce sells products and feeds inventory changes back to Lightspeed

  • Product management is done in Lightspeed for all values that are synced by the extension: Price, images etc. while WooCommerce provides the beautiful storefront.
     

This is what defines a 1-way sync scenario using this extension to sync Lightspeed with your WooCommerce store: Lightspeed overrules / manages WooCommerce product inventory while WooCommerce feeds selected info (inventory, sku, descriptions, etc…) back to it. We try to depict this in our little header graphic.

Due to the fact that Lightspeed is the deciding factor in this system, we call Lightspeed the “Source of Truth”.

​

The whole scenario is not a 2-way sync in a way that:
 

Initial Setup 2-way sync (not available)

  • WooCommerce has some products

  • Lightspeed has some products

  • WooCommerce and Lightspeed get scanned and compared upon each sync or import request

  • Products that match on both sides get linked to each other

  • Products missing on either side get copied over
     

With that in mind, let’s begin with the initial import.

Setup

Enable your Subscription – Connect to WooCommerce.com
It is important to keep this plugin up to date as there are constant updates and fixes that get released with each new version. In order to receive updates, connect your site to WooCommerce.com by navigating to WooCommerce -> “My Subscriptions”.

1.png

More details on how to do this here: https://docs.woocommerce.com/document/managing-woocommerce-com-subscriptions/
 

Authorize with Lightspeed
1. Go to: Lightspeed > Settings > Store Settings.

2. Click the Connect to Lightspeed button:

2.png

3. Log into Lightspeed, and click the Authorize Application button when redirected to the Lightspeed Retail page:

3.png

4. Confirm your site when the WooCommerce API connector requests it.

Once confirmed, you’ll be redirected to your site. If authorization completed successfully, a success message and your store name will appear on the Settings page:

5.png

Enable stock management

5-1.png

Under WooCommerce -> Settings -> Products -> Inventory, we highly recommend you have “Enable stock management” enabled. This setting allows WooCommerce to automatically adjust inventory as customers make orders, cancel them, etc. The plugin leverages WooCommerce’s actions and hooks around these types of behaviors to know when to trigger sync events.

Configuration

Store Settings

Primary Inventory Store Configuration

You must set one primary inventory source for WooCommerce.

Tick the primary inventory store – this is the store that the plugin will use to sync inventory to and from.
Save changes.

6.png

Report Errors
Enabling Report Errors will send errors related to the plugin to the Woocommerce Lightspeed Integration development team. This allows us to improve the plugin and provide you with faster service. We do not collect any personal information and errors will be removed from our system within a maximum of 60 days.

Woo Product Sync

On the Woo Product Sync tab, you can designate the default status of the product upon import:
 

Product status on import

7.png

This will apply to all products on import. Variation products will inherit the status from their parent matrix/variable product. This means that even if the setting is set to “Draft”, newly added variation products will go straight to a “Publish” status if their parent product is already live and published. Also note that upon installation the default status is set to “Draft”.

​

SKU Strategy

8.png

When importing a Lightspeed product in WooComerce, you can select which SKU value you would like to use. The options are:
 

  1. System SKU

  2. Custom SKU

  3. Manufacturer’s SKU

  4. Plugin Default – see here for more info
     

If the value is empty in Lightspeed, it will come in as empty in WooCommerce.

​

Image Compression Strategy

9.png

The plugin uses Cloudinary to download images from Lightspeed. The options are low, better (eco), or best. Plugin default will use the eco setting which results in smaller files of slightly lower visual quality.

​

Set empty Sale Price on zero


If the Lightspeed Sale Price is $0.00, this setting will set the Sale Price of the corresponding WooCommerce product to an empty value.

​

Selective sync for WooCommerce products


You can select which product properties should get updated for WooCommerce when pulling data from Lightspeed

10.png

On the initial import of a Lightspeed product into WooCommerce, all the product properties will be present, however on subsequent updates the Selective Sync settings allow you, for example, to only have “Stock Quantity” and “Regular Price” and “Sale Price” be synced from Lightspeed on a sync event. All other properties will not be overwritten! This can be useful if you want to publish products in WooCommerce without the sync event overwriting images, descriptions, etc that you may have setup in WooCommerce but not Lightspeed.

​

The properties you can selectively sync are:

​

  • Name – in Lightspeed, this is the description. In Woo, it will be the product title.

  • SKU – in Lightspeed, you have 3 different options for SKU – Custom SKU,  Manufacturer’s SKU or System SKU – the plugin use the first SKU value it can find in that order.

  • Regular Price – the “Default” price field in Lightspeed

  • Sale Price – You will have to create new “Sale” Price Level in Lightspeed read this section on how to set this up.

  • Stock Quantity – the value “In Stock” value under the Details tab in Lightspeed

  • Image – all of the images set up in Lightspeed for a particular product will be downloaded to WooCommerce. The first image in your Lightspeed gallery will be set as the featured image in WooCommerce. If it is a variable/matrix product, then the parent product’s first image in the gallery will be used as the featured image.

  • Attributes – If the product is a matrix product, then the plugin will try to convert these attributes into product attribute taxonomy terms in WooCommerce, otherwise if this is unchecked, the plugin will use custom attributes by default.

  • Tags – New tags will be added but old tags will not be removed.

     

Prune Deleted Variations

11.png

When you click on the “Manual Update via Lightspeed” button a product, this setting will tell the plugin to automatically delete any variations that have been deleted in Lightspeed for matrix products. In WooCommerce, this translates to automatically deleting variations in a variable product.

12.png

Ignore Archived Lightspeed Products


You can tell the plugin to ignore archived items upon loading them into the import table. This is a setting in the Lightspeed Settings page:

13.png

This means all of your archived items in Lightspeed will not show up in the Lightspeed import table in WooCommerce.

Lightspeed Product Sync

Selective sync for Lightspeed Products

14.png

Once a product is imported from Lightspeed into WooCommerce, you can select which properties of a WooCommerce product should sync back to Lightspeed when the product is updated in WooCommerce. This means the properties in Lightspeed will be overwritten once the update is complete. Examples of updates are:

​

  • Updating a product in the Admin dashboard (includes all types: variations, simple or variable)

  • Bulk updates on the Product Admin page

  • Any stock quantity changes, such as:

    • Stock quantity reductions after checkout

    • Stock quantity increase after an order refund

    • Stock quantity increase after an order cancellation

Background Jobs

15.png

You can enable/disable three background jobs and set them to run on intervals ranging from 5 seconds to 1 hour:

​

Lightspeed Product Changes

Looks at the timestamp field to determine which products were recently modified in Lightspeed. “Recently modified” means changes to:
 

  • Inventory

  • SKU/Description/Pricing

  • Images
     

The plugin will look at all of the properties that are checked off in the Selective Sync for WooCommerce Products settings and update those properties for the associated WooCommerce product.

​

New Lightspeed Products

Looks for newly created Lightspeed products. When it finds new products, it will inform you with a notice:

16.png

If the product is a newly created variation, it will automatically add that variation to the associated WooCommerce variable product.

​

Action after auto-loading products

17.png

If the “New Lightspeed products” job is enabled, then you will also have the option to select what action to take after a product is auto-loaded. You have three options:

​

  • Loaded into the Product Importer – Products will be loaded in to the product importer but not imported to WooCommerce.

  • Imported into WooCommerce, but do not link – Import the auto-loaded Lightspeed Product into WooCommerce – but do not actively sync it.

  • Imported & linked with Woo – Import the auto-loaded Lightspeed Product into WooCommerce –  and actively sync it.

     

Lightspeed Product Attribute Sets

Looks for newly created product attribute sets. Automatically creates new product attributes in WooCommerce under Products -> Attributes.

Usage

Product Importer

Under Lightspeed -> Product Importer you can import and link Lightspeed products with your WooCommerce store.

The Product Importer is a staging platform for managing products from Lightspeed. The state of a product in the Importer represents the state of the product in Lightspeed.
 

Below are steps on how to use the Product Importer.
 

1. Load Products into the Product Importer

To import Lightspeed products into WooCommerce, you first have to load products into the Product Importer. There are two ways to load products into the importer: Searching Lightspeed for specific products or Bulk Load all of your Lightspeed products.
 

Searching Lightspeed for specific products

Click on the “Search Lightspeed” button on the Lightspeed Importer page:

18.png

After clicking on “Search Lightspeed” a modal will pop up where you can search for Single or Matrix products:

19.png

The “Search Lightspeed” modal allows you to perform a real-time search of Lightspeed products

​

Tick the products you want to load into the Importer and click “Apply” at the top left of the results table. The products should then load up in your Importer.

​

Bulk Load all of your Lightspeed products

Click on the “Load Products from Lightspeed”:

20.png

Bulk Load all of your Lightspeed Products into the Product Importer

​

​

After clicking on “Load Products from Lightspeed” you will see a spinner showing you the progress around loading all your Lightspeed products into the Importer:

21.png

Once all of your products have been loaded, the spinner will disappear and the page will refresh and show your products.

​

2. Import & Link Lightspeed Products with WooCommerce

Once products are loaded from Lightspeed POS, your screen should populated a table with products. For example:

22.png

WooCommerce Lightspeed POS Import Page with Products

​

​

There are two actions that can be performed on products loaded from Lightspeed:
 

  • Import & Link with Woo – Imports the Lightspeed product into WooCommerce and then links it with Lightspeed. What does this mean? Your product is now available in WooCommerce >> Products. It is published and visible in the front end. Also a sync link relationship is now established. The WooCommerce product and it’s Lightspeed source product are now linked to each other. The extension installs an Action Scheduler job that runs every five seconds, to ensure that items with established sync links are added to the sync list. Products are checked against Lightspeed for any changes every five seconds and additionally on these events.

  • Remove – Removes the products from the Product Importer table. You can re-add this product by using the “Search Lightspeed” button in case you removed it by accident.
     

Once products are loaded into the importer table, they can be bulk imported using the check boxes and “Bulk actions” dropdown menu. Select “Import & Link with Woo” and then click “Apply.”

​

For imported products, the actions that can be performed are different:
 

  • Edit – Redirects you to the associated WooCommerce edit product page.

  • Update via Lightspeed – Since the product is already imported, this will perform a manual pull from Lightspeed and update the product.
     

Once a product is imported, it can only be removed from the importer table after the product has been deleted and removed from the trash.

ls-product-sync

Matrix/variable product support

In Lightspeed, “Matrix Products” are equivalent to WooCommerce’s “Variable Products“. We recommend you read the documentation on both platforms before using this plugin because these concepts take some time to learn. Both of them.

​

On the Lightspeed page, Matrix items have a “stacked” look, which is different from single items. It displayed a “-” for the SKU and inventory columns. Importing and syncing Matrix items is the same as importing single items.

Importing Matrix/variable products

When importing a Matrix product from Lightspeed into WooCommerce, a new variable product is created and the following properties are downloaded and automatically generated:
 

Syncing with Matrix items is straightforward. Whenever inventory is set for variation items, it pushes that data to Lightspeed. Also, every five seconds a sync job will pick up on any changes made to variations in Lightspeed and then proceed to update the variations in WooCommerce.

Clear All Loaded Products

Clears out all loaded Lightspeed product data from the database – think of this as starting with a clean slate. This will remove all relationships between products in Lightspeed and WooCommerce but will not delete products in either.

23.png

Categories

WooCommerce Lightspeed POS also allows you to import product categories with one click. Go to your Lightspeed settings located at Lightspeed >> Settings and click on the “Categories” tab.

24.png

Subcategories

While Lightspeed allows sibling categories to have identical names, WordPress does not. In WordPress each slug (URL path) must be unique. Make sure that subcategories that share the same parent all have unique names.

25.png
Remove “Uncategorized” category

The plugin will attempt to remove the “Uncategorized” Woo category when importing a product from Lightspeed. If the product that’s being imported does not have any categories associated with it, then it will still apply the “Uncategorized” category since all products in Woo require to be part of at least one category.

26.png

Tags

Tags are added if they are selected in the selective sync tabs.

Old or deleted Tags/Categories in Lightspeed

Due to the nature of this import, product categories and tags are only applied not removed. The sync does add active categories to products, but so far it does not remove obsolete ones, when you remove them on the Lightspeed side.

Create Products from WooCommerce to Lightspeed POS

When using this extension you should initially create your products in Lightspeed and then import them into WooCommerce. However you can send WooCommerce products that are already created and missing on the Lightspeed side to Lightspeed from the product detail page as a one-time initial setup step.

​

To do this, click the Create this product in Lightspeed button in the Lightspeed Settings meta box on the right side:

image 1.webp

This creates the product in Lightspeed with the following data points sent over:

​

  • SKU – this will show up under the “Custom SKU” field in Lightspeed

  • Images (gallery and single images are supported)

  • Inventory

  • Price – regular price and sale price are supported

​

After this the sync relationship defaults to Lightspeed being the source of truth. The WooCommerce product will not continue to send these values from WooCommerce to Lightspeed but will be managed by the Lightspeed side as long as the sync link is active.

Create Products from WooCommerce to Lightspeed POS

When using this extension you should initially create your products in Lightspeed and then import them into WooCommerce. However you can send WooCommerce products that are already created and missing on the Lightspeed side to Lightspeed from the product detail page as a one-time initial setup step.

​

To do this, click the Create this product in Lightspeed button in the Lightspeed Settings meta box on the right side:

image 1.webp

This creates the product in Lightspeed with the following data points sent over:

​

  • SKU – this will show up under the “Custom SKU” field in Lightspeed

  • Images (gallery and single images are supported)

  • Inventory

  • Price – regular price and sale price are supported

​

After this the sync relationship defaults to Lightspeed being the source of truth. The WooCommerce product will not continue to send these values from WooCommerce to Lightspeed but will be managed by the Lightspeed side as long as the sync link is active.

Manual Sync via Lightspeed

You can trigger a manual product sync by either using the Product Importer and using the “Update via Lightspeed” row action there:

image 2.webp

Or by using the “Manual Update via Lightspeed” button located in the sidebar with each single product view in the WooCommerce backend.

image 3.webp

Action Scheduler Jobs

Three recurring action scheduler jobs will be added and run on the selected intervals once the plugin is active:

​

  1. wclsi_poll – checks for any changes in Lightspeed items such as inventory changes, image updates, and other generic updates like description changes.

  2. check_for_new_ls_prods – checks for newly created Lightspeed items.

  3. wclsi_poll_ls_attribute_sets – checks for new product attributes.

​

You can trigger these jobs manually whenever you’d like by going to Tools -> Scheduled Actions and click on the “Pending” category:

Image 4.webp

Relinking

Sometimes a WooCommerce product may lose its link to its corresponding Lightspeed product for various reason (e.g. a user error caused the Lightspeed product to be deleted from the Lightspeed import table).

​

The “Relink with Lightspeed” button re-establishes this link by looking up the Lightspeed product based off the SKU value using the following logic: if the Lightspeed product already exists in the Lightspeed import table, then it will try to re-establish the link there first, otherwise it will make an API call to Lightspeed and see if there are any products that match the SKU. If there is a match, then it will try and re-establish the link that way.

Image 5.webp

The “Relink with Lightspeed” button is located under the “Lightspeed Settings” metabox on the product page.

Frequently Asked Questions

Troubleshooting

Logs

​

Under WooCommerce -> Status -> Logs there are two log files that the plugin automatically generates for you and one that is generated if debugging is turned on:

Image 8.webp

wclsi-errors.log

​

This log captures exceptions/errors and is very helpful to check on the health status of the plugin.

​

wclsi-sync-events.log

​

Captures general sync data that is pulled and pushed to/from Lightspeed.

​

wclsi-debugger.log (only generated if debugging is turned on)

​

Captures data related to debugging such as bucket level, etc.

​

Database Structure

The following tables are installed upon activation (with wp_ being the prefix):

Image 9.png

wp_wclsi_items stores most essential info such as:

​

  • id a general item id to identify a product within the WooCommerce Lightspeed plugin tables.

  • item_id the item id used by Lightspeed.

  • wc_prod_id the post id used by WooCommerce. NULL if product has not been imported to WooCommerce.

  • wclsi_import_date shows date and time of the import. NULL if not imported.

  • wclsi_last_sync_date shows date and time of the import. NULL if never synced.

  • wclsi_is_synced shows 1 if a product has an active sync link to Lightspeed from WooCommerce. NULL if product is not linked from WooCommerce to Lightspeed.

Software Requirements

These software settings are required to run WooCommerce Lightspeed without issues.

​

  • PHP 7.2 – 7.4

  • MySQL 5.6 or higher,

  • PHP Max Execution time of 300s or higher.

​

You can use this plugin: WP-Serverinfo to check your environment settings.

For editing PHP parameters, please see this blog post.

PHP Version 8 not supported (yet)

The plugin does not support PHP Versions 8+ … yet. This is because of the limitation WordPress imposes around unit testing. There is a hard requirement to use PHPUnit 7+ which only supports PHP versions up to PHP 7.3 (although it technically seems to work up to 7.4).

​

Once WordPress expands support to PHPUnit 8+ (which supports PHP versions >= 7.2), then we will explore supporting PHP versions 8+. If you want to follow WordPress’s progress on this, you can follow the open issue here: https://core.trac.wordpress.org/ticket/46149.

Current Release

See the changelog for full details.

​

If you have current issues please open a support ticket with us, to access the most current development version which fixes outstanding issues.

Versioning

As of September 22nd, 2021, our future versions will be numbered in the following way:

​

  • Format: 0.0.0

  • First number represents major feature releases.

  • Second number represents regular updates.

  • Third number represents patches.

Read before updating

  • The most important step is to take a full backup. You must be prepared to rollback using a backup. Test your rollback first, before you update! An untested backup might still leave you stranded.

  • Your sync links and all other data prior to the update will be preserved. However we recommend three important steps besides a backup: testing, testing, testing. If you need assistance, please open a support ticket with us and we will guide you through the update process.

Integrations

General

All releases of this plugin get tested thoroughly with the current WooCommerce and WordPress version at the time of the release. No other plugin combinations are tested, therefore you should not assume automatic integration with other plugins. Here is a list of missing integrations that are frequently requested:

​

Missing integrations

​

  • GoDaddys inhouse plugins seem to be not compatible with the upcoming 1.4.3 release, they must be disabled.

  • This extension is not WordPress Multisite compatible.

  • This extension does not support Windows server. Use on Windows on your own risk.

  • This extension does not support WPML.

  • This extension does not support Archive, Layaway or backorders.

  • This extension does not support custom taxonomies of any kind. For example: WooCommerce  Brands and Lightspeed Brands are not supported. We recommend to setup Brands as categories instead.

  • Multiple stores can be read but are not supported for syncing data. If you have multiple Lightspeed stores, you must designate one of them as your primary store that the plugin will use to read inventory values from as well as sync inventory values to.

  • This extension does not sync sales data. Only inventory changes are sent. WooCommerce order data is not sent over. (sales syncing beta released Nov. 2021)

  • Product Vendors  is not supported.

  • Lightspeed eCom is not supported.

  • Caching is not supported. Any Varnish, object or other cache must exclude all WooCommerce product pages, cart and checkout.

bottom of page