Lightspeed — Adapter Guide¶

Which integration is this? Consolidated knowledge pack for Lightspeed Restaurant (K-Series / L-Series, formerly iKentoo) in the new JS-adapter model (see ADR 0004); it absorbs the former expert-lightspeed repo, now frozen.

Maturity: STUB. This is the least-complete pack — most facts are marked [TBC] and need confirmation against the live Restaurant API. The older direct integration in kds-management-service/service/LightspeedService/ is the best source of truth for the concrete quirks below; the JS adapter scripts under scripts/adapters/lightspeed/ are not yet built.

Covers Lightspeed Restaurant only — NOT Retail (R-Series), eCom (E/C-Series), or Golf. Those are separate products with different APIs.

Provider Info¶

Field	Value
Slug	`lightspeed`
Auth Type	`oauth`
Base URL	`[TBC]` — `https://api.lightspeedhq.com/restaurant/`? (legacy `https://api.ikentoo.com/`)
API Docs	https://developers.lightspeedhq.com/ (confirm Restaurant API portal)
Model	Pull for outlets/products; order status via webhook or poll `[TBC]`

Authentication¶

OAuth 2.0 (authorization-code → access_token + refresh_token):

Authorization: Bearer {accessToken}

Input fields: input.config.accessToken, input.config.refreshToken, input.config.companyId, input.baseUrl. Access tokens are short-lived — the script may need refresh logic. Token TTL [TBC].

Key Concepts¶

Multi-location accounts use locationId per outlet — scope every call to the right business/location.
Lightspeed has Restaurant (L/K-Series) and Retail (R-Series) with different APIs — use Restaurant.

Quirks & Constraints¶

Quirk	Detail	Confidence
No Modifiers concept	Lightspeed has no Modifiers — everything is an Item. To model an item with modifiers you create it as a Combo. The adapter must map Cata modifier groups → Combo structure.	kds production
Fees are Items	Fees are open-price Items (positive or negative), not a separate fee structure. The adapter creates fee items.	kds production
Pricing via Order Profiles	A PLU's price varies only via Order Profiles — pricing cannot be customised externally. Via Deliverect, price changes must be made in Lightspeed directly.	kds production
Price format	Decimal values (e.g. `15.50`), matching Cata — confirm per endpoint.	`[TBC]`
Legacy iKentoo	Formerly iKentoo; some endpoints/fields may still say `ikentoo`.	`[TBC]`
Rate limits	Retail uses a leaky-bucket (≈1 req/s + burst); Restaurant may be similar. Respect `429` / `Retry-After`.	`[TBC]`
Pagination	offset/limit or cursor.	`[TBC]`
Timestamps	UTC ISO-8601; locations carry their own timezone.	`[TBC]`
Flat product sync	One level of modifier groups; ignore the menu tree.	—
Stable identifiers	`itemCode`/`externalId` must use native Lightspeed IDs that persist across syncs.	—

Topic: `test_connection`¶

[TBC] — verify the OAuth token with a cheap read (e.g. GET /api/account).

Topic: `list_remote_outlets`¶

[TBC] — GET /api/locations → [{ id, name, address }].

Topic: `sync_outlet`¶

[TBC] — Lightspeed location/business → Cata outlet (externalId, name, address, contact, timezone, currency, openingHours).

Topic: `sync_products`¶

[TBC] — flat catalog: products → modifier groups (modelled as Combos) → options. itemCode from native PLU; basePrice decimal; remember fees-as-items and the Combo-for-modifiers rule above.

Topic: `order_dispatch`¶

[TBC] — Cata order → Lightspeed order. Order-creation flow (single vs multi-step) and whether fees ride as line items need confirmation.

Topic: `order_status_update`¶

[TBC] — webhook vs poll unknown. Map Lightspeed statuses to Cata ACCEPTED → IN PROGRESS → READY → COMPLETED, CANCELLED from any state. COMPLETED → COMPLETED is ACK-only (duplicate completions).

Changelog¶

2026-06-09 — Consolidated from expert-lightspeed (stub)¶

Merged the expert-lightspeed stub (Restaurant-only scope, iKentoo legacy, leaky-bucket rate limit, base-URL options, verification checklist) with this guide's concrete kds-derived quirks (no-Modifiers/Combo, fees-as-items, Order Profiles pricing). Still a stub — no scripts, no samples.

Open uncertainties (must verify before building)¶

[ ] OAuth flow details and token TTL
[ ] Correct Restaurant base URL (vs legacy iKentoo)
[ ] API versioning, rate-limit algorithm, pagination method, ID format
[ ] Price format per endpoint (decimal vs cents)
[ ] Modifier-group terminology in the Restaurant API (vs the Combo model)
[ ] Order-creation flow (single vs multi-step)
[ ] Webhook availability for order status (else poll)
[ ] Collect sample payloads for all five topics