Skip to content

Lightspeed POS Integration

Menu Location: Products > Lightspeed

Overview

The Lightspeed integration connects your Kiva Logic online store with your Lightspeed Retail point-of-sale system, keeping inventory in sync between the two.

Primary Functions:

  • Two-way inventory sync between Lightspeed Retail and Kiva Logic
  • Real-time webhook updates when POS sales or inventory changes occur
  • Hourly full sync as a safety net
  • Product import from Lightspeed for linking to existing Kiva Logic products

Key Concept: Lightspeed is the source of truth for inventory. The system tracks three numbers for each linked product:

Number Description
Lightspeed Count What Lightspeed reports as available. Matches what you see in Lightspeed POS.
In Stock Lightspeed Count + Reserved. Total inventory including units claimed by online orders.
Reserved Units claimed by online customer orders. Spoken for but not yet fulfilled.

The key formula: Lightspeed Count = In Stock - Reserved

Initial Setup

Step 1: Connect to Lightspeed

Lightspeed connects via OAuth:

  1. In the Settings panel, enter the OAuth Client ID and Client Secret from your Lightspeed developer app registration and click Save Credentials
  2. Click the Connect to Lightspeed button (shown prominently near the top of the page)
  3. You'll be redirected to Lightspeed to authorize access, then redirected back automatically
  4. Your Store URL is set automatically once connected

A legacy Private Token field is also available under Settings for older setups that are not using OAuth. Lightspeed has deprecated personal tokens, so OAuth is the supported path going forward.

Step 2: Enable the Feature

In the Status panel, toggle Feature to enabled.

Step 3: Register Webhooks

  1. In the Webhooks panel, click Create Webhooks
  2. You should see product.update and inventory.update webhooks listed as active
  3. Toggle Webhook Processing to enabled in the Status panel

Step 4: Fetch Products from Lightspeed

  1. In the Sync Actions panel, click Fetch All Products
  2. This imports your Lightspeed product catalog into the system for linking
  3. Products already imported are skipped automatically
  1. Go to Products > Lightspeed Product Linker
  2. Match each Lightspeed product to the corresponding product in Kiva Logic (or create a new one)
  3. See the Lightspeed Product Linker guide for matching tools available on that page

Step 6: Run Initial Sync

  1. Click Pull Full Sync from Lightspeed to pull current inventory counts for all linked products
  2. Setup is complete

How the Two-Way Sync Works

POS Sale (Lightspeed to Kiva)

Starting: Lightspeed Count = 40, In Stock = 45, Reserved = 5

  1. Someone buys 1 item at the register
  2. Lightspeed fires a webhook: count is now 39
  3. Kiva updates: Lightspeed Count = 39, In Stock = 39 + 5 = 44
  4. Available to online shoppers = 44 - 5 = 39 (matches Lightspeed)

Online Order (Kiva to Lightspeed)

Starting: Lightspeed Count = 39, In Stock = 44, Reserved = 5

  1. Customer adds 3 items to their order online
  2. Reserved goes from 5 to 8
  3. Available = 44 - 8 = 36
  4. Kiva pushes 36 to Lightspeed and updates Lightspeed Count = 36
  5. POS now shows 36 available (so in-store staff see accurate stock)

Order Cancelled (Kiva to Lightspeed)

Starting: Lightspeed Count = 36, In Stock = 44, Reserved = 8

  1. Customer cancels their order of 3 items
  2. Reserved goes from 8 to 5
  3. Available = 44 - 5 = 39
  4. Kiva pushes 39 to Lightspeed and updates Lightspeed Count = 39
  5. Stock is back in Lightspeed for in-store sales

Loop Prevention

When Kiva pushes a count to Lightspeed, Lightspeed fires a webhook back. The system tracks version numbers to recognize these "echo" webhooks and ignores them automatically.

Full Sync Fallback

Every hour, the system pulls all inventory from Lightspeed to catch any missed webhooks. You can also trigger this manually with the Pull Full Sync from Lightspeed button. The full sync only updates already-linked products, it does not create new product entries.

Page Layout

Connection Status

Near the top of the page, a panel shows whether you are connected to Lightspeed (via OAuth) and lets you disconnect. If your connection has expired, this panel prompts you to reconnect, and a warning banner also appears on the main Dashboard until you reconnect.

Page Links

Quick navigation to related pages:

  • Product Linking -- match Lightspeed products to Kiva Logic products
  • Webhook Queue/Processing -- view and troubleshoot incoming webhook events

Sync Actions

  • Push Inventory to Lightspeed -- sends current available counts for linked products to Lightspeed
  • Pull Full Sync from Lightspeed -- pulls all inventory from Lightspeed and updates linked products
  • Fetch All Products / 10 / 1 -- imports new Lightspeed products into the system for linking (skips existing)

Settings

  • OAuth Client Credentials -- your Lightspeed developer app's Client ID and Client Secret, saved before connecting
  • Store URL -- your Lightspeed Retail store URL (set automatically once connected via OAuth)
  • Private Token (legacy) -- a Lightspeed personal token, only needed if not using OAuth
  • Outlet ID -- auto-detected from the API; only set manually if needed

Status

  • Auth Mode -- shows whether you're connected via OAuth, a legacy Private Token, or not connected
  • Feature -- master toggle for the Lightspeed integration
  • Webhook Processing -- toggle to enable/disable processing of incoming webhooks
  • Auto-Create Products -- toggle described below under New Products from Lightspeed
  • Pending Webhooks -- number of webhook events waiting to be processed
  • Last Full Sync -- timestamp of the most recent hourly sync
  • Webhook Secret -- security key appended to webhook URLs, with an option to regenerate it

Webhooks

Displays currently registered webhooks and their status. You can create, toggle, or delete webhooks from here.

Dev Tools

Shows the currently registered webhook URL and allows overriding the base URL for testing with tools like ngrok.

New Products from Lightspeed

There are two ways new Lightspeed products are handled, controlled by the Auto-Create Products toggle in the Status panel:

Manual (default, Auto-Create disabled):

  • New products appear on the Product Linking page for review
  • An admin must either link it to an existing Kiva product or create it as a new product
  • Nothing goes live on the customer-facing site until an admin approves it
  • Good when Lightspeed contains POS-only items (bags, merchandise) that shouldn't show online

Auto-Create (Auto-Create Products enabled):

  • Incoming product/inventory webhooks create a matching Kiva product automatically
  • Good when starting from a clean Lightspeed catalog where every product should exist in Kiva

Troubleshooting

Inventory Not Updating

Check:

  1. Both Feature and Webhook Processing are enabled in the Status panel
  2. Webhooks are listed as active in the Webhooks panel
  3. Check the Webhook Queue page for errors
  4. Try clicking Pull Full Sync from Lightspeed to force an update

"Unable to Fetch Outlet Id"

Your Store URL or API token/connection may be incorrect. Double-check your OAuth connection (or Store URL and Private Token if using the legacy method) in the Settings section. The outlet ID is fetched automatically when the page loads.

"Lightspeed Connection Expired" Banner

If your OAuth connection expires, a warning appears on the Dashboard and inventory sync pauses. Click Reconnect on the banner, or use the Connect to Lightspeed button on this page, to re-authorize.

Webhooks Show "No Webhooks Found"

Click Create Webhooks in the Webhooks panel. Make sure you're connected to Lightspeed first.

Products Not Appearing on Linker Page

Click Fetch All Products to pull products from Lightspeed. Then go to Product Linking to match them.

Want to Force a Fresh Sync

Click Pull Full Sync from Lightspeed to re-pull all inventory counts immediately for all linked products.

  • Lightspeed Product Linker -- link Lightspeed products to Kiva Logic products
  • Lightspeed Webhook Queue -- view and reprocess incoming webhook events

Best Practices

  1. Lightspeed is source of truth -- make inventory adjustments in Lightspeed, not in Kiva Logic
  2. Link products carefully -- verify you're matching the correct products between systems
  3. Monitor the webhook queue -- check periodically for errors or stuck webhooks
  4. Don't disable webhooks unnecessarily -- they provide real-time sync; the hourly sync is only a safety net

For additional help, contact Kiva Logic support.