🔗 Lightspeed Retail (R-Series): Data Mapping & Synchronisation

This guide details the specific field mappings and logic used for the Lightspeed R-Series POS integration. Unlike C-Series integration, this connection uses the Retail API endpoints (e.g., /Item.json, /Sale.json).

🗺️ Data Mapping Details

1. Products

Endpoint: /Item.json

Optiply	Lightspeed R-Series	Logic / Notes
Remote ID	`itemID`	Unique identifier.
Name	`description`	Product name
SKU Code	`customSku` or `systemSku`	Priority: Uses `customSku`. If empty, defaults to `systemSku`.
Unit Price	`Prices.ItemPrice.amount`	Uses the price where `useType = "Default"`.
Stock Level	`itemShops.ItemShop[shopId].qoh`	Quantity on Hand (QOH) for the selected shop.
Status	`archived`	If `archived = true` → Disabled.
EAN Code	`ean`	-
Assembled	`itemType`	If `itemType` is `'assembly'` or `'box'` → True.
Created At	`createTime`	-
Minimum Stock	`itemShops.ItemShop[shopId].reorderPoint`	-

⚠️ Important SKU Logic:

Lightspeed Retail has two SKU types:

systemSku: Read-only, system-generated.
customSku: User-editable.

Optiply prioritises the customSku. This means if you update the custom SKU in Lightspeed, it will update in Optiply.

📦 Item Types:

default: Normal items (Synced).
non_inventory: Inventory not tracked (Filtered out—not synced).
assembly: Components build assembly items (Mapped as Assembled).
box: Box items break down into singles (Mapped as Assembled).
Variants: Items with itemMatrixId > 0 are treated as individual items; the matrix structure does not affect the integration.

2. Product Compositions

Endpoint: /Item.json (Assembly Logic)

Optiply	Lightspeed R-Series
Composed Product ID	`assemblyItemID`
Part Product ID	`componentItemID`
Part Quantity	`quantity`
Remote ID	`itemComponentID`

3. Suppliers

Endpoint: /Vendor.json

Optiply	Lightspeed R-Series
Name	`name`
Remote ID	`vendorId`

4. Supplier Products

Endpoint: /Item.json?load_relation=["ItemVendorNums"]

Optiply	Lightspeed R-Series	Notes
Name	`description`	-
Remote ID	`itemVendorNums.ItemVendorNum.itemVendorNumID`	Unique identifier.
Price	`itemVendorNums.ItemVendorNum.cost`	Supplier Cost Price.
SKU Code	`customSku` or `systemSku`	Same logic as Products.
Status	`archived`	If `archived = true` → Disabled.
EAN Code	`ean`	-
Product ID	`itemVendorNums.ItemVendorNum.itemID`	-
Supplier ID	`itemVendorNums.ItemVendorNum.vendorID`	-
Preferred	`defaultVendor`	The Default Vendor in Lightspeed is marked as Preferred.

5. Sell Orders

Endpoint: /Sale.json

Optiply	Lightspeed R-Series	Logic / Notes
Total Value	`calcSubTotal`	-
Remote ID	`saleID`	-
Placed Date	`createTime`	-
Deleted	`voided`	If `voided = true`, the order is marked as Deleted in Optiply.

Note on Voided Orders: The voided field indicates a completed sale was cancelled or returned. Optiply handles this by deleting the sales order to ensure your historical demand data remains accurate.

6. Sell Order Lines

Endpoint: /Sales.json?load_relations=["SaleLines"]

Optiply	Lightspeed R-Series
Product ID	`saleLine.itemId`
Remote ID	`saleLine.saleLineId`
Quantity	`saleLine.unitQuantity`
Subtotal Value	`saleLine.unitPrice` * `quantity`

7. Buy Orders (R-Series → Optiply)

Endpoint: /Order.json

Optiply	Lightspeed R-Series	Logic
Placed Date	`orderedDate`	-
Supplier ID	`vendorID`	-
Total Value	`totalCost`	-
Completed	`complete`	If `complete = 'true'`, set to `receivedDate`.
Expected Delivery	`arrivalDate`	-
Remote ID	`orderID`	-

8. Buy Order Lines (R-Series → Optiply)

Endpoint: /Order.json?load_relations=["OrderLines"]

Optiply	Lightspeed R-Series
Buy Order ID	`OrderLine.OrderID`
Subtotal Value	`OrderLine.total`
Product ID	`OrderLine.itemID`
Remote ID	`OrderLine.orderLineID`
Quantity	`OrderLine.quantity`

9. Buy Orders (Optiply → R-Series)

Endpoint: /Order.json

Optiply	Lightspeed R-Series
Placed Date	`orderedDate`
Supplier ID	`vendorID`
Expected Delivery	`arrivalDate`
Optiply ID	`refNum`

10. Buy Order Lines (Optiply → R-Series)

Endpoint: /OrderLine.json

Optiply	Lightspeed R-Series
Buy Order ID	`orderID`
Product ID	`itemID`
Quantity	`quantity`
Price	`price`

11. Receipt Lines (Item Deliveries)

Endpoint: /Shipment.json?load_relation=["OrderShipmentItems"]

Optiply	Lightspeed R-Series	Notes
Quantity	`qtyReceived`	-
Occurred	`timeStamp`	-
Remote ID	`orderShipmentId`	-
Buy Order Line ID	`orderId` + `itemId`	Composite identifier.

❓ Frequently Asked Questions (FAQs)

Which SKU does Optiply use?

Lightspeed Retail has two SKU fields: systemSku (generated by Lightspeed) and customSku (editable by you). Optiply prioritises the customSku. If that field is empty, we fall back to the systemSku.

Why are some of my products missing?

Check the "Item Type" in Lightspeed. Optiply filters out items marked as non_inventory (service items or non-tracked goods). We only sync items with types default, assembly, or box.

What happens if I void a sale in Lightspeed?

If you mark a sale as voided (cancelled/returned) In Lightspeed, Optiply automatically marks that Sales Order as Deleted. This prevents the returned sale from inflating your sales history and affecting future forecasts.

How are "Box" items handled?

Items marked as box in Lightspeed are treated as assembled products in Optiply. This allows us to understand that the box is composed of multiple single items.

Lightspeed R series- Data Mapping & synchronisation