eCom-to-Retail Data Bridge Manual (Beta)

App Settings
Products
Orders
Logs

Once installed and setup, our Data Bridge app will allow for the syncing of order and catalog info between your Lightspeed Retail account and one or more Lightspeed eCom websites. The Data Bridge can:

Automatically import new products from Retail into eCom
Detect and sync certain product changes from Retail to eCom
Automatically import new eCom orders into Retail
Detect and sync certain order changes from eCom to Retail and from Retail to eCom
Combine quantity on hand of products from multiple Retail shops and report that combined total as the stock quantity available in your eCom website(s); you can turn on/off combined quantity on hand per each eCom website
Turn on/off price syncing from Retail to eCom per each eCom website (i.e. you can have one eCom site sync pricing changes from Retail while another eCom website uses pricing you manage autonomously in that eCom's admin interface)

Important Considerations

Here we'll highlight what the Data Bridge currently does and does not sync between Retail and eCom.

Warning: We strongly recommend you avoid any add-on apps from third-party vendors that may modify catalog content as that may cause issues with the Data Bridge app functionality. If an app indicates it is not compatible with Lightspeed's omnichannel connector - unless tested in advance - it's best to avoid it for the Data Bridge as well.

Retail-to-eCom Product Syncing

If you want the app to manage an item, the product must be created in Retail only. The Data Bridge pushes new product data in one direction only, from Retail to eCom. See the product field map below for more information.

Product Custom Fields, Tags, and Vendors do not sync between Retail and eCom with the Data Bridge. If using Retail's e-commerce module, web short/long descriptions are not currently supported in the Data Bridge.

eCom-to-Retail Order Syncing

If you want the app to manage an order, the order must be created in eCom only. The Data Bridge pushes new orders in one direction only, from eCom to Retail. A sale created in Retail outside the app will not be managed or linked to an order in eCom by the app.

Limited data changes are synced by the app between Retail and eCom. See the Order section further down for more information.

Please note the following limitations:

Quotes made in Retail are not reflected in eCom (or vice-versa).
Tags created in Retail are not reflected in eCom.
Refunds and returns are processed within Retail and are not reflected in eCom.

Preventing Data Loss

The Data Bridge app is intended to sync data between Retail and eCom, it is not intended to store data. While the app does store some data, it's only for internal app logic (i.e. determining if product info has changed since last sync). This data is not available to "reload" into eCom or Retail. You should follow the Lightspeed help documentation regarding data backup and preventing data loss: https://retail-support.lightspeedhq.com/hc/en-us/articles/360019200693

Preparing Existing Catalog Data

Matching Field Between eCom(s) and Retail Products

If we're dealing with existing catalog data in any of your eCom sites, we'll need a field to match between the product in eCom and the product in Retail (Lightspeed doesn't provide a unique field, that we can use, to match the items between the two systems). The fields we can use to match products are Custom SKU, Manufacturer SKU, or UPC. Whichever field you choose, you'd need to make sure the field value in each eCom matches the field value in LSR (so the app knows which products match between the two systems). AdVision can work with you to help identify the best field to use for your catalog.

Once the bridge has matched up existing catalog data, a matching unique value won't be a concern for any future new items processed through the bridge as the bridge will create it's own unique ID for each item it exports from Retail and imports into your eCom sites, so this matching field using a unique value only matters for this initial setup, you won't have to worry about it for future items.

eCom Product Sets

Due to the differences between Retail's Attribute Sets and eCom's Product Sets, the bridge uses each Retail Matrix's name as the Product Set name in eCom. So to match attribute sets/matrices from Retail to eCom, you'll want to ensure the Product Set in eCom has the same name as the Matrix in Retail. For example, in Retail, if you have a matrix named "Widget A Matrix", the bridge will look for a Product Set of the same name in eCom. If it doesn't find a product set with this name, it will attempt to create a new one.

if you have Product Sets in your eCom catalog, you should ensure their named using the matching Matrix name from Retail so the bridge can match them between the two systems.

Additionally, Matrix names in your Retail catalog should be unique.

App Settings

API Connection Credentials

API URL, Account ID, Access Token, and Refresh Token are fields that hold the credentials the app uses to connect to your Lightspeed Retail account. If you unsure about these fields, it's best to leave them alone.

Basic Settings

Alert Email on Errors: Set the email address you'd like to be alerted if the app errors in syncing any information
Last Product Sync from Retail: Set the date/time of the last product sync from Retail so the app knows how far back to look for changes on it's next sync. If you believe a product update was missed, you can set this date/time to just before the product change was made and the app will attempt to find it on it's next sync.
Last Order Sync from Retail: Set the date/time of the last order sync from Retail so the app knows how far back to look for changes on it's next sync. If you believe an order update was missed, you can set this date/time to just before the order change was made and the app will attempt to find it on it's next sync.
Push Orders When: This determines when the app will push new eCom orders into Retail. You can choose to have new eCom orders created as a Sale within Retail when a) the order is first created in eCom or b) when the order is marked as paid in eCom

Lightspeed Retail Settings

These are the default settings for the app to use when syncing data from Retail.

Retail Shop ID: Set the shop ID you'd like the app to send eCom orders to and pull product stock quantity on hand from.
Use Combined Quantity of All Retail Shops: If you'd like the app to combine the stock qty from all shops into a compiled total, check this box. When checked, for each product into your Retail catalog, the app will combine the quantity on hand of that product for each shop in your Retail account and report that total as the product's stock quantity to eCom.
Retail Employee ID: When creating a sale in Retail, the app needs to assign the sale to an employee. Set to the chosen employee's numeric, system ID from Retail.
Retail Register ID: When creating a sale in Retail, the app needs to assign the sale to a register. Set to the chosen register's numeric, system ID from Retail.
Tax Categories: In order to match eCom taxes to Retail taxes, the tax name in eCom needs to be mapped to the sales tax numeric, system ID in Retail. To do this, provide the eCom tax name, an equal sign, then the Retail sales tax ID, like so:

VAT=1

So in this example, "VAT" is the tax name in eCom and "1" is the sales tax ID in Retail. If you need to support multiple taxes, simply separate each by a comma, like so:

VAT=1,GST=3

In this example, we have eCom's VAT tax set to sales tax 1 in Retail, and eCom's GST mapped to sales tax 3 in Retail.
Auto-generate Retail Tax Categories: if you're using automatically calculated taxes in eCom, it's best to activate this setting, which will create a tax category in Retail for each tax rate needed from an eCom order. E.g. if a particular item in eCom order is being charged 4% state tax and 3% county tax, the bridge will ensure there is a tax category in Retail for that total tax rate of 7%.
Payment Methods: In order to match eCom payment methods to Retail payment options, the eCom payment method name needs to be mapped to the payment option's numeric, system ID in Retail. To do this, provide the eCom payment method name, an equal sign, then the Retail payment option ID, like so:

invoice=10

So in this example, "invoice" is the payment method name in eCom and "10" is the payment option ID in Retail. If you need to support multiple payment options, simply separate each by a comma, like so:

invoice=10,authorize.net=5

In this example, we have eCom's invoice payment method set to payment option 10 in Retail, and eCom's authorize.net method mapped to payment option 5 in Retail.
Retail Shipping Item ID: Since Retail doesn't offer a "shipping cost" field, when creating an eCom sale in Retail, eCom has to assign the shipping cost to product setup in Retail that represents the shipping cost. This "shipping item" needs to be setup in your Retail catalog as a non-inventory item with a price of 0. When the app creates the eCom order as a sale in Retail, it will assign the shipping cost from the eCom order to the price of this shipping item in Retail.
Retail Payment Fee Item ID: If any payment options you offer in eCom incur a payment fee, we'll setup an item in your Retail catalog to represent that cost.
Root Category ID: If you want to limit which categories are used in bridge sites, you can set a root category. This indicates to the bridge to only use categories within the specified root category. E.g. if you have categories like:

Root A
- Sub AA
- Sub AB

Root B
- Sub BA
- Sub BB

If you set your root category to "Root B", only categories "Sub BA" and "Sub BB" would be used by the bridge. Any other categories would be ignored.

Pricing

Pricing is Tax Inclusive: If checked, indicates that the pricing is setup to be tax inclusive. This is the default setting, which can be customized per each eCom website, if you so choose.
Sync Pricing from Retail: If checked, indicates you'd like any pricing changes from Retail to update eCom website. This is the default setting, which can be customized per each eCom website, if you so choose.
Retail Product Price Level: Indicates which "price level" from your Retail catalog should be used for the sale price for items in eCom
Retail Product "Old Price" Level: Indicates which "price level" from your Retail catalog should be used for the MSRP/regular price for items in eCom

Criteria for Targeting Products

If you'd like to limit when the app pulls new or updated product information from Retail to eCom, you can indicate a particular field in Retail that has to be set to a specific value in order for the product to be synced to eCom.

Trigger Product Sync Field: Select the field you'd like to use to determine if a product should be synced from Retail to eCom
Trigger Product Sync Value: Indicate the value that should be set in the selected field to determine if a product should sync from Retail to eCom.

For example, if I'm creating new products and don't want them sent to eCom until I'm sure they're completely setup, I could select a field here (that I'm not using for something else), like "Custom SKU", and indicate a specific value, like "ready to sync", to tell the app not to grab any products (new or changed) unless I've set the Custom SKU field to "ready to sync".

eCom Stores

If you're using multiple eCom websites within the bridge app, you can manage the specific settings for each here. Each eCom store's settings will use the default settings (specified above) unless you select to customize a setting for a particular eCom store. The per-store settings you can modify include:

Retail Shop ID: Which shop in Retail should this eCom send it's orders to
Retail Employee ID: Employee to use when creating new sales from this eCom
Retail Register ID: Register to use when creating new sales from this eCom
Pricing is Tax Inclusive: Indicates if the prices from this eCom are tax inclusive or not
Sync Pricing from Retail: Indicate if you want price changes from Retail to sync to this eCom
Retail Product Price and "Old Price" Levels: Indicate which price levels to use for the pricing in this eCom
Tax Categories: Map the tax category names from this eCom to the appropriate sales tax IDs in Retail
Auto-generate Retail Tax Categories
Payment Methods: Map the payment method names from this eCom to the appropriate payment option IDs in Retail
Use Combined Quantity: Indicate if this eCom's product stock quantities should use the combined quantity from all Retail shops or only the quantity on hand from the one Retail shop this eCom is assigned to
Root Category ID

After making any setting changes, be sure to click "Save Settings" button.

Products

Under the "Products" tab in app admin, you can view and search the products that have synced through the app, and force a manual sync for a product if you'd like. Each product listed shows it's Retail Item ID, System SKU and Description, along with a button to perform a manual sync.

Syncing Products

The Data Bridge app checks for new or updated products in Retail every five minutes. If it detects any products that have been created or changed, it will attempt to create or update those products in your eCom site(s).

Below is an outline of the basic relations between Retail and eCom fields. Some fields only sync when first creating the product in eCom, while others will sync whenever changes are made to the field for existing products. "When" column indicates if the field is used with new ("Creation") or existing ("Updates") products, or both.

Retail Field	eCom Field	When	Notes
Assigned shop's Quantity on Hand or all shops' Combined Qty	Variant Stock Qty	Creation and Updates	Depending on your app settings, app will update stock qty in each eCom based on quantity on hand in Retail
Price Level (from "Retail Product Price Level" app setting)	Variant Price	Creation and Updates, depends on settings	If set to sync pricing in app settings, will update existing product's on price change. Always used when handling new product
Price Level (from "Retail Product 'Old Price' Level" app setting)	Variant Old Price	Creation and Updates, depends on settings	If set to sync pricing in app settings, will update existing product's on price change. Always used when handling new product
Sales Tax	Variant Tax Category	Creation
Manufacturer	Brand	Creation
Category	Category	Creation	Updates product's primary category assignment.
Image	Variant Images	Variant: Creation and Updates	One image per variant
Custom SKU	Variant Article Code	Creation and Updates
UPC or EAN	Variant EAN	Creation and Updates	Uses UPC if value is set, otherwise uses EAN
Manufacturer SKU	Variant SKU	Creation and Updates
Default Cost	Variant Cost	Creation and Updates
Description	Product and Variant Titles	Creation and Updates
Weight	Variant Weight	Creation and Updates	Requires e-commerce module in Retail
Width	Variant Size X	Creation and Updates	Requires e-commerce module in Retail
Height	Variant Size Y	Creation and Updates	Requires e-commerce module in Retail
Length	Variant Size Z	Creation and Updates	Requires e-commerce module in Retail

Some important notes about how the app works with your catalog information:

Matrices and Attribute Sets

If you're using matrices in your product setup in Retail, the Data Bridge will use the matrices and attribute sets to create appropriate parent/child products in eCom.* Specifically, the app will take the matrix/attribute sets from Retail and create similar product sets within eCom. The product set in eCom is then used to generate the appropriate matrix/child products.

eCom Issue: Some eCom accounts experience a bug when product sets are applied via the API. Lightspeed is aware of the issue but has no ETA for resolution. If the bridge sees that eCom has failed to generate appropriate variants based on the assign product set, it will manually add the variants required.

*Warning: Be sure NOT to modify attribute or attribute value labels in either eCom or Retail AFTER the app has already used them to create products in eCom. The labels are the only way the app can identify/match each attribute value between systems, so changing the label after the app has handled it will result in issues (e.g. duplicate products, app unable to identify matching products between the two systems).

For example, if you have an attribute named "Color", and after the app has processed the product using that attribute, you change the attribute name to "Colour", the app will see that as a new attribute and act accordingly.

Another example, if you have an attribute named "Color" with a value named "Blue", and after the app has processed that product, you change the value from "Blue" to "Teal" in Retail, the app will see that as a new, additional attribute value and act accordingly.

The same warning applies to moving products/variants in or out of a matrix after the bridge has handled the items. Currently the bridge cannot automatically handle changing an item from a matrix variant to a non-matrix variant (or vice versa), so it is recommend that you plan carefully in implementing your matrix setups BEFORE the bridge handles items. The roadmap does include updating the app to better manage this type of change, but for the time being it's best to avoid changing an items' matrix setup. Please contact AdVision support if you have an issue with managing a matrix change through the bridge.

Brands

The app will take the Manufacturer assigned to an item in Retail and look for that as a Brand within eCom. For example, if you set Manufacturer = "Acme" in Retail, the app will look for Brand = "Acme" in eCom. If not found, the app will create the new Brand in eCom.

The Data Bridge app works off the numeric, system generated IDs for manufacturer/brand, so changing the manufacturer's name in Retail will not cause the brand's name to update in eCom. So if you want to update a manufacturer/brand's name, you'd need to:

a) manually change the name in both Retail and eCom, or

b) create a new manufacturer in Retail with the new name you want to use, then assign that new manufacturer to the items you want updated - this will cause the app to see the new Manufacturer, create a new brand with that manufacturer's name in eCom, and update the items in eCom with that new brand.

Syncing New Products from Retail to eCom(s)

When the app detects new items in Retail, it will attempt to create those same items in your eCom(s) using the fields listed above in the product field map. If the new product is using a new matrix/attribute set in Retail, the Data Bridge will create a matching product set in eCom and use that to generate the necessary variants, then assign the individual product variants from Retail to the matching variants in eCom.

If you have "Sync Pricing" turned off in the app settings, when the app is creating a new product, the pricing from Retail is used for the initial creation of the item,(but future pricing changes for that item would not sync if "sync pricing" is turned off.

Syncing Product Changes

When syncing changes for an existing product (a product that already exists in the app), the app checks the following fields for changes, and if it detects any changes, attempts to update the appropriate fields in your eCom(s):

Stock Qty: If quantity on hand for item has changed, app will update eCom product/variants with new stock qty
Pricing: If set to sync pricing from Retail, and one or more of the assigned "price level" prices has changed, app will update eCom product/variants with new pricing
Brand: If Retail item's Manufacturer field changes, updates product's Brand in eCom
Custom SKU: Updates eCom variant's Article Code
UPC (or EAN) : Uses UPC if set, if not set uses EAN; updates eCom variant's EAN field
Manufacturer SKU: Updates eCom variant's SKU
Default Cost: Updates eCom variant's Cost
Description: Updates eCom product/variant's Title
Image: If you add or change the main image assigned to a product/variant in Retail, the related eCom variant image will be updated
Category: Updates eCom product's primary category assignment

If you want to perform a manual sync for an item, go to the "Products" tab in app admin and click the button labeled "Sync from Retail to eCom(s)" for the product you want to sync. This performs a manual sync when clicked, which means the app grabs the product's current data from Retail and attempts to determine if any changes have been made to the product that should be synced to your eCom site(s).

If you believe the app has missed the creation of a new product, or updates to multiple existing products, you can get the app to try again by going to the Settings tab and setting the "Last Product Sync" to an earlier date/time. If you set the Last Product Sync to a date/time before the creation/update of products that you want the app to handle, then click Save Settings, the next time the app checks for new/updated products, it will look back as far as the Last Product Sync date/time that you've set.

Orders

The Data Bridge uses eCom's webhooks which alert the app when events occur with your eCom orders. The events the app currently listens for are order created, order updated, and order paid.

Syncing New Orders from eCom to Retail

New orders are only synced in one direction, from eCom to Retail. When the app is alerted to a new order from eCom, it will attempt to take that order and create the necessary sale to represent it in Retail. Several settings, covered in the settings section above, are used to accomplish the appropriate sale creation in Retail:

Retail Shop ID: Determines which shop the app should create the sale in
Retail Employee ID: Which employee to use to create the sale
Retail Register ID: Which register to use to create the sale
Tax Categories:Translates tax categories used in eCom to the sale's taxes setup in Retail
Payment Methods: Translates the payment method used in eCom to the sale's payment option in Retail
Retail Shipping Item ID: If there is any shipping cost in the eCom order, this item will be added to the Retail sale the cost of shipping will be set as this item's price (i.e. this item represents the order's shipping cost)

Note: if you're using multiple eCom sites in your Data Bridge, each of these settings can be customized per each eCom (if so desired).

When creating a sale, the app does the following:

Attempts to match all the items in the eCom order to items in your Retail catalog. To match products between eCom and Retail, the app keeps a database matching each eCom's product IDs to the matching item's Retail item ID. This is why it is essential that any products in your eCom catalog be created in Retail and imported into eCom by the Data Bridge app, otherwise if an item is ordered in eCom and the app doesn't have a record of it, it will fail to fully build the sale in Retail.
Takes the eCom order's customer information and attempts to find a matching customer in your Retail account. The app does this by attempting to match the email address. If it finds any customers with a matching email address, it will then make sure that the customer found matches (case-insensitive) the eCom customer's First Name, Last Name, State, Country, Zipcode and Address (Line 1). If all that information matches, the app will use the exisitng customer's record in Retail. If the app fails to find an already existing customer in Retail, it will create a new customer record in Retail to use with the new sale
If the eCom order has payments, the app will include the payment info (payment methods and amounts) when creating the Retail sale, and attempt to set the sale to completed. If the payments on the eCom order don't meet or exceed the order's total due, the sale will be created, but will fail to be marked as completed.
If the eCom order is has no payment information, the app will set completed to false for the new Retail sale.

eCom Order Marked as Paid

If an eCom order is not marked as paid when it's created, but is marked as paid in eCom at a later date, the app will be alerted to this and attempt to add the necessary payment information to the Retail sale and mark it completed.

Syncing Order Changes from eCom to Retail*

* only for orders imported from eCom through the Data Bridge app

eCom will alert the Data Bridge if an order is updated. Currently the app will update a Retail sale:

If order payment status is newly set to paid, add payment details to Retail sale and mark as paid
If order status is completed, completed shipped or completed picked up, set Retail sale to completed
If order status is cancelled, set Retail sale to not completed

Currently no other data is synced on order updates from eCom.

Syncing Sale Changes from Retail to eCom*

* only for orders imported from eCom through the Data Bridge app

The Data Bridge checks for updates to Retail sales every five minutes. If the app detects that an order has been updated, it will updated the related eCom order:

If sale is newly voided, set eCom order status to cancelled

Currently no other data is synced on order updates from Retail.

If you want to perform a manual sync for an order, either from eCom-to-Retail or Retail-to-eCom, go to the "Orders" tab in app admin and click the appropriate button ("Sync from Retail to eCom" or "Sync from eCom to Retail") for the order you want to sync. This performs a manual sync when clicked, which means the app grabs the order's current data from the one system and attempts to determine if any changes have been made to the order that should be synced to the other system.

If you believe the app has missed the creation of a new order (or group of orders) in eCom, you can get the app to try again by going to the Settings tab and setting the "Last Order Sync" to an earlier date/time. If you set the Last Order Sync to a date/time before the creation the orders that you want the app to handle, then click Save Settings, the next time the app checks for new orders in eCom, it will look back as far as the Last Order Sync date/time that you've set.

Logs

Under the "Logs" tab in app admin, you can view a recent history of any data sync events that the Data Bridge has attempted. Both errors and successes are listed here. For each sync record, you can click the "Details" link to view the specifics of that log. When viewing details, any errors will be listed in red.

If you set the "Alert Email" setting (outlined in the Settings section above), errors can also be emailed to you to alert you to the problems as they occur.

Diego Cassio

Posted · Updated

Confirmation