REST API for Lightspeed Restaurant K-Series, the flagship cloud restaurant POS. Covers items and rich items, menus, modifiers and discounts, orders (Order & Pay), checks and payments, floorplans and tables, staff and webhooks, financials and aggregated sales, tax breakdown, PMS integration, reservations, and ID cards.
openapi: 3.1.0
info:
version: 1.0.0
title: Lightspeed Restaurant K Series API
description: "**Lightspeed Restaurant** offers a **REST API** in order to communicate with the data in the system. These APIs are built using the RESTful standards and adhere to the basic verb interactions as defined by the REST standard.\nDetailed developer guides can be found in the [Lightspeed Restaurant API Portal](https://api-portal.lsk.lightspeed.app/).\nThese services are in continuous development and subject to change. Please find our versioning policy [here](https://api-portal.lsk.lightspeed.app/quick-start/versioning).\n"
x-logo:
altText: Lightspeed Commerce
url: static/lightspeed@2x.png
contact:
name: Lightspeed Commerce
url: https://api-portal.lsk.lightspeed.app/
x-generated-from: documentation
x-last-validated: '2026-06-02'
x-source-url: https://api-docs.lsk.lightspeed.app/source.json
servers:
- url: https://api.trial.lsk.lightspeed.app
description: Demo URL
x-bump-branch-name: demo
- url: https://api.lsk.lightspeed.app
description: Production URL
x-bump-branch-name: prod
tags:
- name: Rich Item
- name: Tax Breakdown
- name: Staff
description: Staff API. Authorisation Code grant type is required for this API with permission ROLE_CONFIG_USERS.
- name: Reservations for Platforms
- name: PMS
- name: Items
- name: ID Cards
- name: Financial
description: "V1 endpoints (`/f/finance/...`) for retrieving sales and financial data.\n\nFor the newer V2 versions of these endpoints see FinancialV2\n\n### V1 behaviour\n\n- **Sorting**: No guaranteed sorting order; internal transformations may alter order unpredictably\n- **Transitory Accounts / Unsettled Sales**: Returns closed transactions only\n- **Pagination**: `pageSize` max of 1000. Uses HATEOAS `_links` with `self` and `nextPage` URLs\n- **Daily endpoints** (`getDailyFinancials`): No pagination, no hard cap on results. May have slower response times for larger data sets\n- **Backoffice transactions**: Historical dating supported. Transactions will be dated to a past date if the action impacts past reports. Can query transactions by original business date\n- **Backoffice modifications** (payment method change and canceling): Modifications appear on the original transaction date\n"
- name: FinancialV2
description: "V2 endpoints (`/f/v2/...`) for retrieving sales and financial data.\n\n### Endpoint Mapping\n\n| V1 Endpoint | V2 Endpoint |\n|-------------|-------------|\n| `getFinancials` (`/f/finance/{id}/financials/{from}/{to}`) | `getSales` (`/f/v2/business-location/{id}/sales`) |\n| `getDailyFinancials` (`/f/finance/{id}/dailyFinancials`) | `getBusinessDaySales` (`/f/v2/business-location/{id}/sales-daily`) |\n\nResponse DTOs are nearly identical to V1 with the exceptions noted below\n\n### V2 behaviour\n\n- **Sorting**: Explicitly sorted by `timeClosed`\n- **Transitory Accounts / Unsettled Sales**: Returns closed transactions and ensures no transitory (unclosed) transactions are included in reporting\n- **Pagination**: `pageSize` max of 100. No HATEOAS `_links`; uses `nextPageToken` string for pagination instead\n- **Daily endpoints** (`getBusinessDaySales`): No pagination, no hard cap on results. May have slower response times for larger data sets\n- **Backoffice transactions**: Historical dating not currently supported — transactions appear as if created at current time. Transactions can only be found by the date/time they were actually created. *Historical dating support is planned for a future release.*\n- **Backoffice modifications** (payment method change and canceling): Modifications appear on the date the modification was performed, not the original transaction date\n\nIf you need to query transactions by their original business date (e.g. for historical reporting or reconciliation); The V1 endpoints may be more suitable until backwards compatibility is added to V2 for this aspect.\n"
- name: Order and Pay
- name: 'Order and Pay: Webhook'
webhooks:
apeOrder notification:
post:
summary: Order Notification
operationId: onlineOrderNotification
description: What your webhook implementation will receive when placing an order
tags:
- Order and Pay
requestBody:
content:
application/json:
examples:
successfulWithoutAccountInfo:
summary: successful
value:
status: SUCCESS
ikentooAccountId: '2114502594134196'
ikentooAccountIdentifier: A123080.14
thirdPartyReference: REF11
type: ORDER
readyForPickUp:
summary: ready for pickup
value:
thirdPartyReference: order-wFUBVgHNGPAJsryIrSaE
businessLocationId: 247158188015618
status: READY_FOR_PICKUP
account:
clientCount: 2
uuid: 5a81c7f4-9e2f-4db2-965d-6946a4f9c25b
openDate: 2021-12-21T13:24:49.265+0000
paidAmount: '4.00'
serviceCharge: '0.00'
name: Order NZVV
currentAmount: '4.00'
staffName: Manager
staffId: 31930
salesEntries:
- id: 304087979524125
itemName: Appetizer 2
itemSku: '21'
unitAmount: '4.00'
quantity: 1
modifiers: []
amountWithTax: '4.00'
amountLessTax: '3.33'
discountedAmount: '0.00'
grossUnitAmount: '4.00'
active: true
taxIncluded: true
paymentEntries:
- paymentMethodDescription: API Payment
externalReference: '1234567890'
paymentMethodCode: APM
amountPaid: '4.00'
paymentDate: 2021-12-21T13:25:25.082+0000
active: true
ikaccountId: A17700.3
tableNumber: 3
posId: 17700
ikentooAccountId: 304087979524124
ikentooAccountIdentifier: A17700.3
type: ORDER
failure:
summary: failure
value:
status: FAILURE
reason: A consumer already exists for this email address with a different external reference.
thirdPartyReference: REF12212
succesfulWithAccount:
summary: successful with account info
value:
thirdPartyReference: order-wFUBVgHNGPAJsryIrSaE
businessLocationId: 247158188015618
status: SUCCESS
account:
clientCount: 2
uuid: 5a81c7f4-9e2f-4db2-965d-6946a4f9c25b
openDate: 2021-12-21T13:24:49.265+0000
paidAmount: '0.00'
serviceCharge: '0.00'
name: Order NZVV
currentAmount: '4.00'
staffName: Online Order
staffId: 31930
salesEntries:
- id: 304087979524125
uuid: 1b8d016e-2c7f-456d-9349-8476eacd99bf
itemName: Appetizer 2
itemSku: '21'
unitAmount: '4.00'
quantity: 1
modifiers: []
amountWithTax: '4.00'
amountLessTax: '3.33'
discountedAmount: '0.00'
grossUnitAmount: '4.00'
timeOfTransactionUtc: 2023-11-08T13:33:52.641+0000
active: true
subLineItems: []
taxIncluded: true
paymentEntries: []
ikaccountId: A17700.3
tableNumber: 3
posId: 17700
ikentooAccountId: 304087979524124
ikentooAccountIdentifier: A17700.3
type: ORDER
checkWasUpdated:
summary: check was updated
value:
thirdPartyReference: order-wFUBVgHNGPAJsryIrSaE
businessLocationId: 247158188015618
status: CHECK_WAS_UPDATED
account:
clientCount: 2
uuid: 5a81c7f4-9e2f-4db2-965d-6946a4f9c25b
openDate: 2021-12-21T13:24:49.265+0000
paidAmount: '4.00'
serviceCharge: '0.00'
name: Order NZVV
currentAmount: '4.00'
staffName: Manager
staffId: 31930
salesEntries:
- id: 304087979524125
itemName: Appetizer 2
itemSku: '21'
unitAmount: '4.00'
quantity: 1
modifiers: []
amountWithTax: '4.00'
amountLessTax: '3.33'
discountedAmount: '0.00'
grossUnitAmount: '4.00'
active: true
taxIncluded: true
paymentEntries:
- paymentMethodDescription: API Payment
externalReference: '1234567890'
paymentMethodCode: APM
amountPaid: '4.00'
paymentDate: 2021-12-21T13:25:25.082+0000
active: true
ikaccountId: A17700.3
tableNumber: 3
posId: 17700
ikentooAccountId: 304087979524124
ikentooAccountIdentifier: A17700.3
type: ORDER
closed:
summary: closed
value:
thirdPartyReference: order-wFUBVgHNGPAJsryIrSaE
businessLocationId: 247158188015618
status: CLOSED
account:
clientCount: 2
uuid: 5a81c7f4-9e2f-4db2-965d-6946a4f9c25b
openDate: 2021-12-21T13:24:49.265+0000
paidAmount: '4.00'
serviceCharge: '0.00'
name: Order NZVV
currentAmount: '4.00'
staffName: Manager
staffId: 31930
salesEntries:
- id: 304087979524125
itemName: Appetizer 2
itemSku: '21'
unitAmount: '4.00'
quantity: 1
modifiers: []
amountWithTax: '4.00'
amountLessTax: '3.33'
discountedAmount: '0.00'
grossUnitAmount: '4.00'
active: true
taxIncluded: true
paymentEntries:
- paymentMethodDescription: API Payment
externalReference: '1234567890'
paymentMethodCode: APM
amountPaid: '4.00'
paymentDate: 2021-12-21T13:25:25.082+0000
active: true
ikaccountId: A17700.3
tableNumber: 3
posId: 17700
ikentooAccountId: 304087979524124
ikentooAccountIdentifier: A17700.3
type: ORDER
schema:
allOf:
- $ref: '#/components/schemas/apeBaseWebhookInformation'
- properties:
status:
enum:
- SUCCESS
- FAILURE
- IN_DELIVERY
- READY_FOR_PICKUP
- CLOSED
- ABANDONED
- CANCELLED
description: Status of the order operation.
type: string
type:
description: Notification type
default: ORDER
type: string
account:
allOf:
- description: Related account (if the webhook is configured to provide it)
- $ref: '#/components/schemas/apeAccountSnapshot'
type: object
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback
apePayment notification:
post:
summary: Payment Notification
operationId: onlinePaymentNotification
description: What your webhook implementation will receive when placing a payment
tags:
- Order and Pay
requestBody:
content:
application/json:
examples:
successfulPayment:
summary: successful
value:
thirdPartyReference: REF11
businessLocationId: 247158188015618
status: SUCCESS
ikentooAccountId: '2114502594134196'
ikentooAccountIdentifier: A123080.14
type: PAYMENT
failurePayment:
summary: failure
value:
reason: the payment amount is greater than the amount due
thirdPartyReference: REF12212
businessLocationId: 141948669832802
status: FAILURE
ikentooAccountIdentifier: A78094.73
type: PAYMENT
failurePaymentAccountError:
summary: failure with account error
value:
reason: Account not found
thirdPartyReference: REF12213
businessLocationId: 141948669832802
status: FAILURE
errors:
account:
type: ACCOUNT_NOT_FOUND
type: PAYMENT
schema:
allOf:
- $ref: '#/components/schemas/apeBaseWebhookInformation'
- properties:
status:
enum:
- SUCCESS
- FAILURE
description: Status of the order or payment operation.
type: string
errors:
description: Error details when status is FAILURE.
type: object
properties:
timeout:
description: Timeout error details.
type: object
properties:
errorKey:
type: string
example: errors.payment.pos.task_timeout
message:
type: string
example: Not processed before validity ended
account:
description: Account error details.
type: object
properties:
type:
type: string
enum:
- ACCOUNT_NOT_FOUND
- ACCOUNT_ALREADY_CLOSED
- INVALID_TASK
- ITEM_NOT_ADDED
- ITEM_NOT_FOUND
- MISSING_STAFF
- NATIVE_PAYMENT_NOT_SUPPORTED
- OVERPAID
- PAYMENT_ID_NOT_FOUND
- PAYMENT_METHOD_NOT_FOUND
- STAFF_NOT_FOUND
- UPDATE_FAILED
- UNKNOWN
example: ACCOUNT_NOT_FOUND
type:
description: Notification type
default: PAYMENT
type: string
type: object
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback
apeItem availability notification:
post:
summary: Item Availability Notification
operationId: salesRestrictionUpdatedNotification
description: What your webhook implementation will receive when item sales restrictions are updated
tags:
- Order and Pay
requestBody:
content:
application/json:
examples:
itemRestricted:
summary: item restricted
value:
sku: UGG-BB-PUR-06
businessLocationId: 247158188015618
count: 5
countUpdatedAt: '2024-04-04T09:42:00.000+00:00'
status: RESTRICTED
type: ITEM
itemNotRestricted:
summary: item not restricted
value:
sku: UGG-BB-PUR-06
businessLocationId: 247158188015618
count:
countUpdatedAt: '2024-04-04T09:42:00.000+00:00'
status: NOT_RESTRICTED
type: ITEM
schema:
type: object
properties:
sku:
type: string
description: The SKU of the item with updated availability
examples:
- UGG-BB-PUR-06
businessLocationId:
$ref: '#/components/schemas/apeBusinessLocationId'
count:
type:
- integer
- 'null'
format: int64
description: The available count of the item. null indicates no restriction
examples:
- 5
countUpdatedAt:
type: string
format: date-time
description: The timestamp when the count was last updated
examples:
- '2024-04-04T09:42:00.000+00:00'
status:
type: string
enum:
- RESTRICTED
- NOT_RESTRICTED
description: The restriction status of the item
examples:
- RESTRICTED
type:
type: string
description: Notification type
default: ITEM
examples:
- ITEM
required:
- sku
- businessLocationId
- countUpdatedAt
- status
- type
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback
pms-integration{subscriber-host}/charge:
post:
summary: Transaction Details
operationId: transactionDetails
description: "What subscriber endpoint implementation will receive when a transaction is made.\nSubscriber path need to end with `/charge`.\nSubscriber implementation should follow the payload backward compatibility rules below:\n - What considered as backward **compatible**:\n - Addition of new fields, enums, headers, or parameters.\n - Transition from optional to required fields. Which means Lightspeed will consistently send the parameter/field from now on.\n - What considered as backward **incompatible**:\n - Alteration of schema structure, such as switching from a map to an array.\n - Removal of field/enum/header\n - Changes in data types, such as converting from string to integer.\n - Changes of property name\n"
parameters:
- in: header
name: Accept
required: true
schema:
type: string
example: application/json
description: "The expected response content type from subscriber.\nOnly application/json is supported.\n"
- in: header
name: X-Lightspeed-Idempotency-Key
required: true
schema:
type: string
example: LS1_123e4567-e89b-12d3-a456-426614174000
description: "Subscribers should utilize the Idempotency Key to ensure duplicates are handled appropriately on their end.\n"
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/pms-integrationSalesWebhookDto'
responses:
'200':
description: "Subscriber should return this code if it successfully processed the charge request at PMS.\nFollowing that, Lightspeed will mark the PMS charge transaction as SUCCESS as well.\n"
5XX:
description: "If any server error occurs subscriber can pass their own custom message to the POS.\nThe response body content need to follow the schema, else only `5XX {Error Type}` will be sent.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/pms-integrationErrorWebhookDto'
4XX:
description: "If any client error occurs subscriber can pass their own custom message to the POS.\nThe response body content need to follow the schema, else only `4XX {Error Type}` will be sent.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/pms-integrationErrorWebhookDto'
tags:
- PMS Integration
reservation-serviceReservation error notification:
post:
summary: Error notification
operationId: reservationErrorNotification
description: These notifications are sent to the URL provided in the[`errorsWebhookUrl` field](https://api-docs.lsk.lightspeed.app/operation/operation-reservation-servicesetbyplatformcode#operation-reservation-servicesetbyplatformcode-body-application-json-errorswebhookurl).
tags:
- Reservations for Platforms
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/reservation-serviceErrorWebhook'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback.
reservation-serviceReservation integration notification:
post:
summary: Integration notification
operationId: reservationIntegrationNotification
description: These notifications are sent to the URL provided in the[`integrationWebhookUrl` field](https://api-docs.lsk.lightspeed.app/operation/operation-reservation-servicesetbyplatformcode#operation-reservation-servicesetbyplatformcode-body-application-json-integrationwebhookurl).
tags:
- Reservations for Platforms
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/reservation-serviceIntegrationWebhook'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback.
reservation-serviceReservation onboarding notification:
post:
summary: Onboarding notification
operationId: reservationOnboardingNotification
description: These notifications are sent to the URL provided in the[`onboardingWebhookUrl` field](https://api-docs.lsk.lightspeed.app/operation/operation-reservation-servicesetbyplatformcode#operation-reservation-servicesetbyplatformcode-body-application-json-onboardingwebhookurl).
tags:
- Reservations for Platforms
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/reservation-serviceOnboardingWebhook'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback.
reservation-serviceReservation order notification:
post:
summary: Order notification
operationId: reservationOrderNotification
description: These notifications are sent to the URL provided in the[`orderWebhookUrl` field](https://api-docs.lsk.lightspeed.app/operation/operation-reservation-servicesetbyplatformcode#operation-reservation-servicesetbyplatformcode-body-application-json-orderwebhookurl).
tags:
- Reservations for Platforms
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/reservation-serviceOrderUpdate'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback.
reservation-servicePOS reservation updated notification:
post:
summary: POS reservation updated notification
operationId: posReservationUpdatedNotification
description: These notifications are sent to the URL provided in the[`posReservationUpdateWebhookUrl` field](https://api-docs.lsk.lightspeed.app/operation/operation-reservation-servicesetbyplatformcode#operation-reservation-servicesetbyplatformcode-body-application-json-posreservationupdatewebhookurl).
tags:
- Reservations for Platforms
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/reservation-servicePosReservationUpdate'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback.
staff-apiShift notification:
post:
summary: Shift notification
operationId: shiftNotification
description: Notify about a shift event.
tags:
- Staff
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/staff-apiWebhookEventDto'
required: true
responses:
'200':
description: Your server returns this code if it accepts the callback.
paths:
/o/op/data/businesses:
get:
summary: Lightspeed Get Businesses
operationId: apeLookupBusinesses
description: Returns a list of all businesses and business locations associated with the access token.
tags:
- Order and Pay
responses:
'200':
description: Businesses
content:
application/json:
schema:
items:
properties:
name:
example: My Awesome Business
description: The business name.
type: string
id:
example: 454335871
description: The unique identifier for the business.
type: integer
format: int64
businessLocations:
description: The business locations within this business.
items:
properties:
id:
$ref: '#/components/schemas/apeBusinessLocationId'
name:
example: My Awesome Business - Location 1
description: The business location name.
type: string
type: object
type: array
type: object
type: array
examples:
ApeLookupBusinesses200Example:
summary: Default apeLookupBusinesses 200 response
x-microcks-default: true
value:
- name: My Awesome Business
id: 454335871
businessLocations:
- id: 45454565682155
name: My Awesome Business - Location 1
security:
- OAuth2:
- orders-api
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/o/op/data/{businessLocationId}/floorplans:
get:
summary: Lightspeed Get All Floorplans
operationId: apeLookupFloorPlans
description: Returns the floorplans for a specific business location.
tags:
- Order and Pay
parameters:
- schema:
$ref: '#/components/schemas/apeBusinessLocationId'
name: businessLocationId
in: path
required: true
- name: expandTables
in: query
required: false
description: "If true, the response will include the table details for each floorplan.\nIf false, the response will only include the [`name`](https://api-docs.lsk.lightspeed.app/operation/operation-apelookupfloorplans#operation-apelookupfloorplans-200-body-application-json-name) and [`id`](https://api-docs.lsk.lightspeed.app/operation/operation-apelookupfloorplans#operation-apelookupfloorplans-200-body-application-json-id) for the floorplans."
schema:
type: boolean
default: true
responses:
'200':
description: Floorplans
content:
application/json:
schema:
items:
properties:
id:
example: 141948669132976
description: The unique identifier for the floorplan.
format: int64
type: integer
name:
description: The name of the floorplan.
example: Terrace
type: string
tables:
items:
$ref: '#/components/schemas/apeTable'
type: array
type: object
type: array
examples:
ApeLookupFloorPlans200Example:
summary: Default apeLookupFloorPlans 200 response
x-microcks-default: true
value:
- id: 141948669132976
name: Terrace
tables:
- number: 1
reference: abcdefg123456
id: '141948669132977'
active: true
description: Table 1
defaultClientCount: 4
'404':
description: "Not Found\n\nIndicates that the business location has no floorplans configured."
security:
- OAuth2:
- orders-api
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/o/op/data/{businessLocationId}/floorplans/{floorPlanId}/tables:
get:
summary: Lightspeed Get Floorplan Tables
operationId: apeGetTables
description: Returns the tables for a specific floorplan of a business location
tags:
- Order and Pay
parameters:
- schema:
$ref: '#/components/schemas/apeBusinessLocationId'
name: businessLocationId
in: path
required: true
- schema:
$ref: '#/components/schemas/apeFloorPlanId'
name: floorPlanId
in: path
required: true
responses:
'200':
description: Tables
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/apeTable'
examples:
ApeGetTables200Example:
summary: Default apeGetTables 200 response
x-microcks-default: true
value:
- number: 1
reference: abcdefg123456
id: '141948669132977'
active: true
description: Table 1
defaultClientCount: 4
security:
- OAuth2:
- orders-api
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/o/op/data/account-profiles:
get:
summary: Lightspeed Get All Order Profiles
operationId: apeAccountProfiles
description: "Returns a list of active [order profiles](https://k-series-support.lightspeedhq.com/hc/en-us/articles/1260804657389-About-order-prof
# --- truncated at 32 KB (1240 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightspeed-pos/refs/heads/main/openapi/lightspeed-pos-restaurant-k-series-openapi.yml