Skip to content

Lightspeed POS Integration

Menu Location: Products > Lightspeed

Access Level: Administrator

Last Updated: 2026-04-07

Overview

The Lightspeed POS Integration connects your Kiva Logic online store with your Lightspeed Retail point-of-sale system. It provides real-time two-way inventory synchronization so that sales made in-store and online are both reflected accurately across both systems.

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: Get Your Lightspeed API Token

  1. Log into your Lightspeed Retail account
  2. Go to Setup > Personal Tokens
  3. Create a new token
  4. Copy the token string (starts with lsxs_pt_)

Step 2: Configure Settings

  1. Navigate to Products > Lightspeed
  2. In the Settings section:
    • Paste your Lightspeed store URL (e.g., https://yourstorename.retail.lightspeed.app)
    • Paste your API token
    • The Outlet ID is auto-detected from the API, but can be set manually if needed
  3. Click Save for each field

Step 3: Enable the Feature

  1. In the Status panel, toggle Feature to enabled

Step 4: 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 5: Fetch Products from Lightspeed

  1. In the Sync Actions panel, click Fetch All Products
  2. This imports your Lightspeed product catalog into the system
  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
  3. The system suggests matches based on name similarity
  4. Save your matches

Step 7: 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 linked products -- it does not create new product entries.

Page Layout

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 all 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

  • Store URL -- your Lightspeed Retail store URL
  • API Token -- your Lightspeed personal token for API access
  • Outlet ID -- auto-detected from the API; only set manually if needed

Status

  • Feature -- master toggle for the Lightspeed integration
  • Webhook Processing -- toggle to enable/disable processing of incoming webhooks
  • 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

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

When a new product is created in Lightspeed that doesn't exist in Kiva Logic:

  • The product appears on the Product Linking page for review
  • An admin must either link it to an existing Kiva product or leave it unlinked
  • Nothing goes live on the customer-facing site until an admin links it

This prevents POS-only items (bags, merchandise, etc.) from cluttering the online store.

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 may be incorrect. Double-check both values in the Settings section. The outlet ID is fetched automatically when the page loads.

Webhooks Show "No Webhooks Found"

Click Create Webhooks in the Webhooks panel. Make sure your Store URL and API token are configured correctly 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
  • Webhook Queue -- view and process 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

End of Documentation

For additional help, contact Kiva Logic support.