DataBridge v2 (alpha) Manual

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

1. Automatically import new products from Retail into eCom
2. Detect and sync certain product changes from Retail to eCom
3. Automatically import new eCom orders into Retail
4. Detect and sync certain order changes from eCom to Retail and from Retail to eCom
5. 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
6. 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)
7. Each site can use QOH from one specified R-series location or combined QOH from all locations
8. Send each site's orders to a specified R-series location

Important Considerations

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

R-series to C-series 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.

C-series to R-series Order Syncing

If you want the app to manage an order, the order must be created in C-series only.  The Data Bridge pushes new orders in one direction only, from C-series to R-series.  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 R-series and C-series.  See the Order section further down for more information.

Please note the following limitations:

1. Quotes made in Retail are not reflected in eCom (or vice-versa).
2. Tags created in Retail are not reflected in eCom.
3. 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 R-series and C-series, 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 value 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 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

Version 2 of the bridge does NOT use product sets in C-series (due to their limitations). Any matrices in R-series will be created as a product in C-series, and the matrix items will be created as variants within that product.  This is the same way Lightspeed's omnichannel handles matrices between the two systems.

Settings

API Connection Credentials

The API connections between the app and your R-series account and your C-series sites will be setup by AdVision when your app is setup.  If API credentials need to be changed in the future, please contact AdVision support.

Account Settings

1. Alert emails: Set the email addresses you'd like to be alerted if the app errors in syncing any information
2. Currency Code: identifies the currency used in your R-series account.
3. R-series 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. 
4. R-series 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.
5. R-series Out of Balance Payment Type ID: sometimes R-series and C-series calculate slightly different totals (usually a penny high or low).  If you wish the app to automatically handle this scenario, we can setup a special "Out of Balance" payment type in R-series, and when this issue occurs, the app will create a payment using the out of balance type to in the amount needed to "balance" the sale.  This allows the sale to be completed and inventory deducted.
6. 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
7. Disable cancel order on sale void: by default, if the R-series sale is voided, the app will cancel the related C-series order.

Default Site Settings

These are the default settings the app will use for each site in your account.

Inventory

1. Combined Quantity: 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.
2. R-series Inventory Location ID: if not using combined quantity, you can specify which location sites should read QOH from.

Matching

If we're dealing with existing catalog data in any of your eCom sites...

1. Match items using R-series field: select field to match in R-series
2. Match items using C-series field: select field to match in C-series sites
3. Skip items without a match: if enabled, app will not sync items from R-series if it can't find a matching item in C-series

Syncing

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. 

1. R-series Sync Flag Field: Select the field you'd like to use to determine if a product should be synced from Retail to eCom
2. R-series Sync Flag 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 sync any products (new or changed) unless I've set the Custom SKU field to "ready to sync".

1. Visibility on creation: Determine visibility in C-series when the app creates a new variant
2. R-series 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.
3. Require Mapped Category: if working with existing catalog data in C-series, to avoid creating duplicate categories, enable this setting to require each category first be "mapped" (linked from C-series to R-series).  You can map categories under each site in Sites>>select site>>Categories>>click on category to link it to a R-series category.

Pricing

1. Sync Pricing: If enabled, 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.
2. 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.
3. R-series Price Level: Indicates which "price level" from your Retail catalog should be used for the sale price for items in eCom.  Required if syncing pricing
4. R-series "Old Price" Level: Indicates which "price level" from your Retail catalog should be used for the MSRP/regular price for items in eCom. Leave empty if you don't want the app to sync old price.

Ordering

1. R-series Order Location ID: Set the location ID you'd like the app to send eCom orders
2. R-series Order 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.
3. R-series Order 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.
4. Only sync orders after: if you have past orders in C-series, you can set this value to ensure those old orders aren't handled by the bridge.

Taxes

1. 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.
2. Auto-generate 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%.
3. Default Tax Category ID: if auto generating tax categories "By individual rates", set the tax category to create tax classes in.
4. 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.
5. Currency Code: set the base currency code te sites use

Sites

Each eCom site's settings will use the default settings (specified above) unless you select to customize a setting for a particular site.  In addition to managing settings, you can:

• activate/deactivate the site in the app
• Check Site for Updates: app will read current site data and compare to app data to ensure everything is up to date.
• Install/Uninstall
• View Events, Orders, Products, Variants and Categories

Events

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 to view 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.

Account >> Sales

Manage any R-series sales created from C-series orders through the bridge.

Account >> Items

Manage any items synced from R-series.

Account >> Matrices

Manage any matrices synced from R-series.

Account >> Categories

Manage any categories synced from R-series.

Sites >> Orders

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

Sites >> Products

Manage products imported from C-series sites.

Syncing Catalog Data

The Data Bridge app checks for new or updated items in Retail every five minutes.  If it detects any items that have been created or changed, it will attempt to create or update those items in the bridge data.  Any relevant data changes detected within the app will then be dispatched to C-series sites.

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.

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

Matrices and Attribute Sets

If you're using matrices in your catalog setup in Retail, the Data Bridge will use the matrices and matrix items to create appropriate products/variants in eCom.*  Specifically, the app will take the matrix details from Retail and create a product within eCom.  Any matrix items will then be created as variants within that eCom product.

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.

Categories

The app will take the Category assigned to an item in Retail and look for that category (including it's parent category - if any) within eCom.  For example, if you set the category in Retail to Hardware>>Tools>>Hammers, the app will look for those three categories (Hardware, Tools, and Hammers) in eCom.  If any of those categories are not found, the app will create them within eCom.

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

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

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

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 in Retail, the Data Bridge will create a matching product in eCom and then create the individual product variants from Retail as variants in eCom product. 

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 item (a product that already exists in the item), the app checks the following fields for changes, and if it detects any changes, attempts to update the appropriate fields in your eCom(s):

1. Stock Qty: If quantity on hand for item has changed, app will update eCom product/variants with new stock qty
2. 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
3. Brand: If Retail item's Manufacturer field changes, updates product's Brand in eCom
4. Custom SKU: Updates eCom variant's Article Code
5. UPC (or EAN) : Uses UPC if set, if not set uses EAN; updates eCom variant's EAN field
6. Manufacturer SKU: Updates eCom variant's SKU
7. Default Cost: Updates eCom variant's Cost
8. Description: Updates eCom product/variant's Title
9. Image: If you add or change the main image assigned to a item Retail, the related eCom variant image will be updated
10. Category: Updates eCom product's primary category assignment

If you want to perform a manual sync for an item, go to Account >> Items in app admin, select item, then click "Sync from Backoffice to Sites". This will pull latest data from R-series into the bridge, then any changes deteced will be dispatched to the C-series sites.

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:

1. R-series Order Location ID: Determines which shop the app should create the sale in
2. R-series Order Employee ID: Which employee to use to create the sale
3. R-series Order Register ID: Which register to use to create the sale
4. Tax Categories: Translates tax categories used in eCom to the sale's taxes setup in Retail
5. Payment Methods: Translates the payment method used in eCom to the sale's payment option in Retail
6. 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:

1. 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.
2. 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
3. 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.
4. If the eCom order 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:

1. If order payment status is newly set to paid, add payment details to Retail sale and mark as paid
2. If order status is completed, completed shipped or completed picked up, set Retail sale to completed
3. 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:

1. 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 Site >> Orders, select the order, then click TBD ("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.