Lightspeed K-Series Integration Setup

Looking for guided setup? Start Emily in the backoffice for step-by-step guided setup.

Purpose

The Lightspeed K-Series integration connects Upvendo to Lightspeed Restaurant K-Series, a cloud-based POS system widely used in the hospitality industry. It provides read access to menus, items, modifiers, floor plans, orders, payments, and financial data from the Lightspeed POS. This allows merchants to use Upvendo channels (Kiosk, Online Ordering, Table QR) for customer-facing ordering while Lightspeed handles kitchen operations, fulfillment, and in-house POS transactions. The integration uses OAuth 2.0 with PKCE for secure authentication and supports real-time updates via webhooks.

Key Concepts

OAuth 2.0 with PKCE

Lightspeed K-Series uses OAuth 2.0 with Proof Key for Code Exchange (PKCE) via Keycloak OIDC. There are no API keys to manage -- the merchant logs in to their Lightspeed account to authorize Upvendo. The flow works as follows:

Upvendo generates a PKCE code verifier (random 86-character string) and derives a code challenge (SHA-256 hash, base64url-encoded)
An HMAC-signed state parameter is created containing the vendor ID and timestamp, protecting against CSRF attacks
The merchant is redirected to Lightspeed's authorization page with the code challenge, client ID, redirect URI, and scopes
After authorization, Lightspeed redirects back with an authorization code
Upvendo exchanges the code for access and refresh tokens using HTTP Basic Auth (client_id:client_secret) -- tokens are NOT sent in the POST body
The business ID is fetched from the Lightspeed API and stored alongside the tokens

Merchant-Scoped Integration

Lightspeed K-Series is merchant-scoped -- one OAuth connection covers all business locations under that Lightspeed account. However, unlike MplusKassa, Lightspeed does not auto-import locations. You must create locations manually in Upvendo before connecting.

Token Management

Access tokens are managed automatically:

Auto-refresh -- tokens are refreshed using the stored refresh token before they expire, with a 5-minute buffer
Expiry check -- every API call verifies token validity before proceeding
Refresh failure -- if the refresh token is revoked (e.g., password change, session revocation in Lightspeed), the integration is marked as disconnected and requires re-authorization via OAuth

Payment Provider Requirement

Lightspeed handles POS payments internally, but Upvendo still needs Stripe or Viva Wallet for customer-facing payments on Kiosk and Online Ordering channels. Lightspeed does not provide customer payment processing to Upvendo.

Available K-Series API Endpoints

The integration can access the following data from Lightspeed:

Data Type	Endpoint	Notes
Businesses	`/o/op/data/businesses`	Returns list of businesses; first business ID stored on connect
Account Profiles	`/o/op/data/account-profiles`	Order profiles (Click & Collect, dine-in, etc.)
Floor Plans	`/o/op/data/{blId}/floorplans`	Table layout per floor plan
Menus	`/o/op/1/menu/list`	Full menu list for a business location
Menu Load	`/o/op/1/menu/load/{menuId}`	Full menu tree with items, supports `richContent=true`
Modifiers	`/o/op/1/menu/modifiers`	Production instructions / modifiers
Discounts	`/o/op/1/menu/discounts`	Available discounts
Item Availability	`/o/op/1/itemAvailability`	Stock availability per SKU per location
Orders (local)	`/o/op/1/order/local`	Create dine-in orders
Orders (toGo)	`/o/op/1/order/toGo`	Create takeaway orders
Open Checks	`/o/op/1/order/table/getCheck`	Current open orders/checks
Payments	`/o/op/1/pay`	Apply payment to a check
Print Message	`/o/op/1/printMsg`	Print a message on the POS
Tax Rates	`/f/finance/{blId}/tax-rates`	Tax rate codes and multipliers
Payment Methods	`/f/finance/{blId}/paymentMethods`	Available payment methods on POS
Accounting Groups	`/f/finance/{blId}/accountingGroups`	Revenue accounting groups
Financials	`/f/finance/{blId}/financials/{from}/{to}`	Sales for date range (paginated)
Daily Financials	`/f/finance/{blId}/dailyFinancials`	Sales for current business day
Items API	`/items/v1/items`	List, create, update, delete items
Rich Items	`/i/richItem/{businessId}`	Images, descriptions, allergens per SKU
Allergens	`/i/allergens`	All allergen codes with translations

Order Types

Lightspeed K-Series supports two order creation methods:

Local orders (/o/op/1/order/local) -- for dine-in orders with a table assignment
ToGo orders (/o/op/1/order/toGo) -- for takeaway/delivery orders

Both order types include the business location ID, a third-party reference (Upvendo order number), endpoint ID (for webhook callbacks), customer info, account profile code, items with SKUs and quantities, and payment details.

Actions

Create Location (Must Be Done First)

Route: /settings/locations

Go to Locations and create a location manually
Lightspeed does not auto-import locations into Upvendo
Select the location from the topbar before proceeding

Connect via OAuth

Route: /lightspeed -> Settings tab

Click Connect with Lightspeed
You are redirected to the Lightspeed login page
Log in with your Lightspeed Restaurant K-Series account (must be admin/owner)
Authorize Upvendo to access your Lightspeed data
After authorization, you are redirected back to Upvendo
The integration stores your access token, refresh token, and business ID automatically

Verify Connection

Route: /lightspeed -> Status tab

Check that Connection Status shows "Connected"
Click Test Connection to verify API access is working
The business ID should be displayed in the Settings tab

Reconnect (Token Expired or Revoked)

Route: /lightspeed -> Settings tab

Click Reconnect to re-authorize via OAuth
The existing integration record is updated with new credentials
Use this when the access token has expired and cannot be refreshed

Disconnect Lightspeed K-Series

Route: /lightspeed -> Settings tab

Click Delete and confirm by typing "Lightspeed"
The integration is disabled and all credentials are cleared
The merchant's in-house channel is cleared (provider_integrated set to null)
You can reconnect at any time via the Settings tab

Business Rules

Lightspeed K-Series is merchant-scoped: one OAuth connection covers all business locations. Locations must be created manually in Upvendo.
A separate payment provider (Stripe or Viva Wallet) is always required for customer-facing payments on Kiosk and Online Ordering. Lightspeed does not handle these.
Access tokens are refreshed automatically. If the refresh token is revoked (password change, session revocation), the integration must be reconnected via OAuth.
The PKCE code verifier is stored in cache for 10 minutes during the OAuth flow. If the callback is not completed within that window, the flow must be restarted.
The HMAC-signed state parameter prevents CSRF attacks during OAuth. The state is verified on callback using the client secret.
The integration logs up to 100 entries, with the newest first. Duplicate consecutive logs are collapsed by timestamp.
Webhook events from Lightspeed are received at /webhook/lightspeed and verified via HTTP Basic Auth credentials or endpoint ID matching.
Only Lightspeed Restaurant K-Series is supported. L-Series and R-Series are not compatible with this integration.
After disconnecting, no more order or menu data flows from Lightspeed. Reconnecting re-establishes the full data flow.
Rich item data (images, descriptions, allergens) is available per SKU via the Rich Item API. Business-level locale settings control which languages are available for item content.

Order Flow

Orders placed via Upvendo channels are sent to Lightspeed K-Series for fulfillment:

text

Customer places order on Kiosk or Online Ordering
            |
Payment processed via Stripe or Viva Wallet
            |
Upvendo receives successful payment webhook
            |
Order sent to Lightspeed K-Series via API
  - Local order (/o/op/1/order/local) for dine-in
  - ToGo order (/o/op/1/order/toGo) for takeaway/delivery
            |
Lightspeed POS receives order for kitchen preparation
            |
Payment applied to check via /o/op/1/pay endpoint

Order Payload Structure

Each order sent to Lightspeed includes:

businessLocationId -- the Lightspeed business location identifier
thirdPartyReference -- the Upvendo order number (e.g., UPV-001)
endpointId -- the webhook endpoint ID for order status callbacks
customerInfo -- customer first name, last name
accountProfileCode -- the order profile (e.g., COLLECT for Click & Collect)
items[] -- each item with sku and quantity
payment -- payment method, amount, and third-party payment reference

Payment Application

After order creation, a separate payment call applies the payment to the open check:

iKaccountIdentifier -- the check/account ID from the created order
paymentMethod -- typically OOPAYMENT (Online Order Payment)
paymentAmount -- the total amount paid
thirdPartyPaymentReference -- links back to the Upvendo payment record

Token Lifecycle Details

Lightspeed K-Series tokens are managed automatically:

Behaviour	Detail
Auto-refresh	Access tokens are refreshed automatically using the stored refresh token before they expire (5-minute buffer)
Expiry check	Every API call checks token validity before proceeding
Refresh failure	If refresh fails (e.g., refresh token revoked), the integration is marked disconnected
Token exchange	Uses HTTP Basic Auth (`client_id:client_secret`) in the Authorization header, not in the POST body

If tokens cannot be refreshed, reconnect via OAuth from the Settings tab.

Webhook Support

Lightspeed K-Series can push real-time events to Upvendo via webhooks:

Endpoint: /webhook/lightspeed (public URL -- verification handled via credentials)
Verification: HTTP Basic Auth credentials configured via LIGHTSPEED_WEBHOOK_USER and LIGHTSPEED_WEBHOOK_PASSWORD environment variables, with fallback to endpoint ID matching
Events: Order updates, payment confirmations, menu changes (event types defined per Lightspeed webhook registration)
Webhook management: Webhooks can be created (PUT), updated (POST), retrieved (GET), and deleted (DELETE) via the /o/wh/1/webhook endpoints. Locations can be linked/unlinked to webhook endpoints individually.

Rich Items, Allergens, and Item Management

Lightspeed K-Series provides enriched item data through its Rich Item and Items APIs:

Rich Item API

List rich items -- paginated list with images, descriptions, and allergen data per SKU
Get by SKU -- detailed rich item data for a single product
Create/update -- push enriched item data (images, descriptions, allergens) from Upvendo to Lightspeed
Image specs -- retrieve upload specifications for product images
Locale settings -- set which languages are available for item content per business

Allergen Data

The /i/allergens endpoint returns all allergen codes with translations in multiple languages. This data can be mapped to Upvendo's allergen and dietary preference fields when syncing items.

Items API (CRUD)

The Items API supports full create, read, update, and delete operations:

List/search -- filter by business location, SKU, name, with pagination (offset and amount)
Create -- add new items with SKU, name, price, and tax rate
Update -- modify existing items by ID
Delete -- remove items (returns HTTP 204)

Prerequisites Checklist

Before connecting Lightspeed K-Series, complete these in order:

Task	Route	Required
Payment Profile	`/settings/payments`	Yes (Stripe or Viva Wallet)
Billing Profile	`/settings/billing`	Yes
Branding Profile	`/settings/brand`	Yes
Create Location	`/settings/locations`	Yes -- create manually; Lightspeed does not auto-import locations

FAQs

Q: Does Lightspeed K-Series auto-import my locations? A: No. Unlike MplusKassa, Lightspeed does not auto-import locations. You must create locations manually in Settings -> Locations before connecting.

Q: What Lightspeed products are supported? A: Only Lightspeed Restaurant K-Series is supported. L-Series (retail) and R-Series (legacy restaurant) are not compatible.

Q: Do I need to manage API keys? A: No. The integration uses OAuth 2.0 with PKCE, so you just log in with your Lightspeed account. Tokens are managed and refreshed automatically.

Q: What happens when the access token expires? A: Tokens are refreshed automatically using the stored refresh token before they expire (with a 5-minute buffer). If the refresh token is also revoked (e.g., after a password change), you need to click Reconnect in the Settings tab.

Q: Can I use Lightspeed for customer payments? A: No. Lightspeed handles POS-side payments only. You must set up Stripe or Viva Wallet for customer-facing payments on Kiosk and Online Ordering.

Q: How do I check if my connection is working? A: Go to the Lightspeed page -> Status tab and click Test Connection. The status should show "Connected" with a recent last-checked timestamp.

Q: Can I view financial reports through the integration? A: Yes. The integration provides read access to Lightspeed's financial API, including tax rates, payment methods, accounting groups, daily financials, and sales data for date ranges.

Q: Does the integration support item images and allergen data? A: Yes. The Rich Item API provides images, descriptions, and allergen information per SKU. Allergen codes and translations are available via the /i/allergens endpoint.

Q: Can I create items in Lightspeed from Upvendo? A: Yes. The Items API supports full CRUD (create, read, update, delete) operations. Items can be created with SKU, name, price, and tax rate. Rich item data (images, descriptions, allergens) can also be pushed via the Rich Item API.

Q: How does the integration handle multiple business locations? A: The OAuth connection is merchant-scoped, so one connection covers all business locations. Each API call specifies a businessLocationId parameter to target the correct location. Locations must be created manually in Upvendo.

Q: What order profiles (account profiles) are available? A: Lightspeed K-Series supports configurable account profiles like Click & Collect, dine-in, and delivery. Available profiles are retrieved via the /o/op/data/account-profiles endpoint and can be filtered by tag code.

Q: Can I view open checks and floor plans? A: Yes. The integration provides access to floor plans with table layouts and open checks per table or account. This data is available via the floor plans and checks endpoints.

Troubleshooting

"OAuth connection failed"

Verify the Lightspeed account has Restaurant K-Series (not L-Series or R-Series)
Ensure the account has admin or owner permissions
Check that the redirect URI configured in the Lightspeed partner dashboard matches exactly what Upvendo uses
Clear your browser cache and try again from the Settings tab -> Connect with Lightspeed

"Connection test failing after successful OAuth"

The access token may have expired -- click Reconnect to re-authorize
Check the Status tab for the last-checked timestamp and error details
Verify the Lightspeed account is active and not suspended
Check the integration logs for specific error messages

"Business ID is missing"

This means the /businesses API call failed after OAuth
Click Reconnect to re-run the full OAuth + business fetch flow
Contact Lightspeed support if the account has no active businesses

"Token refresh failed"

The refresh token may have been revoked (e.g., password change, session revocation in Lightspeed)
Click Reconnect via OAuth from the Settings tab
If the issue persists, check that the client ID and client secret are correctly configured in the environment

"Webhook not receiving events"

Verify the webhook endpoint is registered in the Lightspeed partner dashboard
Check that the Basic Auth credentials match the LIGHTSPEED_WEBHOOK_USER and LIGHTSPEED_WEBHOOK_PASSWORD environment variables
Review webhook logs in the Lightspeed portal for delivery failures
Ensure the webhook endpoint URL is publicly accessible

PKCE or state verification errors

The PKCE code verifier is cached for only 10 minutes. If the OAuth flow took longer, restart it
State verification failures indicate a potential CSRF attack or a stale state parameter. Restart the OAuth flow from the Settings tab
Ensure only one OAuth flow is in progress at a time per merchant

Verify the business location ID is correct in the integration settings
Check that the Lightspeed account has active menus and items configured
Review the integration logs for API errors
Ensure the OAuth scopes include the necessary permissions for the data you need

Item availability returning unexpected results

Item availability is per-SKU and per-business-location. Ensure you are querying the correct location ID
The availability endpoint supports both GET (with skus[] query params) and POST (with SKU list in body)
Check if the item has been deactivated or removed in Lightspeed

Financial data not loading

Financial endpoints require the business location ID in the URL path
Date range queries use the format {from}/{to} in the URL
Paginated results may require multiple requests -- check if include=payments is needed
Verify the OAuth token has scopes covering financial data access

Order creation returns error

Ensure the businessLocationId is valid and active
Check that all item SKUs in the order exist in Lightspeed's catalog
Verify the accountProfileCode matches a valid account profile for the location
Review the endpointId to ensure it matches a registered webhook endpoint
If using OOPAYMENT as payment method, confirm it is configured in Lightspeed

Disconnecting Lightspeed K-Series

Go to Lightspeed (/lightspeed) -> Settings tab
Click Delete and confirm by typing "Lightspeed"
The integration is disabled and credentials are cleared

After disconnecting:

No more order or menu data from Lightspeed
The merchant's in-house channel is cleared (provider_integrated set to null)
Reconnect at any time via the Settings tab

Lightspeed K-Series Integration Setup ​

Purpose ​

Key Concepts ​

OAuth 2.0 with PKCE ​

Merchant-Scoped Integration ​

Token Management ​

Payment Provider Requirement ​

Available K-Series API Endpoints ​

Order Types ​

Actions ​

Create Location (Must Be Done First) ​

Connect via OAuth ​

Verify Connection ​

Reconnect (Token Expired or Revoked) ​

Disconnect Lightspeed K-Series ​

Business Rules ​

Order Flow ​

Order Payload Structure ​

Payment Application ​

Token Lifecycle Details ​

Webhook Support ​

Rich Items, Allergens, and Item Management ​

Rich Item API ​

Allergen Data ​

Items API (CRUD) ​

Prerequisites Checklist ​

FAQs ​

Troubleshooting ​

"OAuth connection failed" ​

"Connection test failing after successful OAuth" ​

"Business ID is missing" ​

"Token refresh failed" ​

"Webhook not receiving events" ​

PKCE or state verification errors ​

Menu or order data not appearing ​

Item availability returning unexpected results ​

Financial data not loading ​

Order creation returns error ​

Disconnecting Lightspeed K-Series ​

Related Documentation ​

Lightspeed K-Series Integration Setup

Purpose

Key Concepts

OAuth 2.0 with PKCE

Merchant-Scoped Integration

Token Management

Payment Provider Requirement

Available K-Series API Endpoints

Order Types

Actions

Create Location (Must Be Done First)

Connect via OAuth

Verify Connection

Reconnect (Token Expired or Revoked)

Disconnect Lightspeed K-Series

Business Rules

Order Flow

Order Payload Structure

Payment Application

Token Lifecycle Details

Webhook Support

Rich Items, Allergens, and Item Management

Rich Item API

Allergen Data

Items API (CRUD)

Prerequisites Checklist

FAQs

Troubleshooting

"OAuth connection failed"

"Connection test failing after successful OAuth"

"Business ID is missing"

"Token refresh failed"

"Webhook not receiving events"

PKCE or state verification errors

Menu or order data not appearing

Item availability returning unexpected results

Financial data not loading

Order creation returns error

Disconnecting Lightspeed K-Series

Related Documentation