Lightspeed Retail R-Series API
REST API for Lightspeed Retail R-Series (Retail Pro / Cloud). Covers items, sales, customers, employees, shops, and inventory.
OpenAPI Specification
openapi: 3.1.0
info:
title: Lightspeed Retail R-Series API
description: |
OpenAPI 3.1 representation of the Lightspeed Retail R-Series REST API
(the original Lightspeed Retail / Retail Pro cloud POS). The R-Series API
is documented at https://developers.lightspeedhq.com/retail/introduction/introduction/
and exposes account-scoped resources under
https://api.lightspeedapp.com/API/V3/Account/{accountID}. It uses OAuth 2.0
with scope-based access control and supports both JSON (`.json`) and XML
response formats. The numeric `accountID` is not the OAuth client_id; it
must be resolved via `GET /API/V3/Account.json` immediately after the token
exchange and is required for every subsequent account-scoped call.
version: "3.0.0"
contact:
name: Lightspeed Commerce
url: https://developers.lightspeedhq.com/retail/introduction/introduction/
x-generated-from: documentation
x-last-validated: "2026-06-02"
x-source-url: https://developers.lightspeedhq.com/retail/introduction/introduction/
servers:
- url: https://api.lightspeedapp.com/API/V3
description: Lightspeed Retail R-Series API host.
security:
- OAuth2: []
tags:
- name: Account
description: The Lightspeed Retail account associated with the access token.
- name: Item
description: Inventory items sold and tracked in Lightspeed Retail.
- name: Sale
description: Point-of-sale transactions and their line items.
- name: Customer
description: Customer records and contact details.
- name: Catalog
description: Categories, manufacturers, and vendors that classify items.
- name: Staff
description: Employees and shops.
paths:
/Account.json:
get:
summary: Lightspeed List Accounts
operationId: getAccount
description: Returns the Lightspeed Retail R-Series account associated with the access token. Call this immediately after the OAuth token exchange to resolve the numeric accountID required by all other endpoints.
tags: [Account]
security:
- OAuth2: [employee:all]
responses:
'200':
description: The account associated with the access token.
content:
application/json:
schema:
type: object
properties:
Account:
$ref: '#/components/schemas/Account'
examples:
GetAccount200Example:
summary: Default getAccount 200 response
x-microcks-default: true
value:
Account:
accountID: '500123'
name: Sample name
link: example
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Item.json:
get:
summary: Lightspeed List Items
operationId: getItems
description: Returns all active (unarchived) inventory items for the account. Supports filtering by query parameters such as upc, systemSku, and description.
tags: [Item]
security:
- OAuth2: [employee:inventory_read]
parameters:
- $ref: '#/components/parameters/accountID'
- name: limit
in: query
description: Maximum number of records to return per page.
schema:
type: integer
default: 100
- name: offset
in: query
description: Number of records to skip for pagination.
schema:
type: integer
default: 0
- name: upc
in: query
description: Filter items by Universal Product Code.
schema:
type: string
responses:
'200':
description: A page of items.
content:
application/json:
schema:
type: object
properties:
'@attributes':
$ref: '#/components/schemas/Attributes'
Item:
type: array
items:
$ref: '#/components/schemas/Item'
examples:
GetItems200Example:
summary: Default getItems 200 response
x-microcks-default: true
value:
'@attributes':
count: 951
offset: 976
limit: 118
Item:
- itemID: '500123'
systemSku: SKU-1001
defaultCost: '12.50'
avgCost: '12.50'
description: example
upc: example
ean: example
customSku: SKU-1001
manufacturerSku: SKU-1001
categoryID: '500123'
manufacturerID: '500123'
archived: false
Prices: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: Lightspeed Create Item
operationId: createItem
description: Creates a new inventory item in the account.
tags: [Item]
security:
- OAuth2: [employee:inventory]
parameters:
- $ref: '#/components/parameters/accountID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
examples:
CreateItemRequestExample:
summary: Default createItem request
x-microcks-default: true
value:
itemID: '500123'
systemSku: SKU-1001
defaultCost: '12.50'
avgCost: '12.50'
description: example
upc: example
ean: example
customSku: SKU-1001
manufacturerSku: SKU-1001
categoryID: '500123'
manufacturerID: '500123'
archived: false
Prices: {}
responses:
'200':
description: Item created.
content:
application/json:
schema:
type: object
properties:
Item:
$ref: '#/components/schemas/Item'
examples:
CreateItem200Example:
summary: Default createItem 200 response
x-microcks-default: true
value:
Item:
itemID: '500123'
systemSku: SKU-1001
defaultCost: '12.50'
avgCost: '12.50'
description: example
upc: example
ean: example
customSku: SKU-1001
manufacturerSku: SKU-1001
categoryID: '500123'
manufacturerID: '500123'
archived: true
Prices: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Item/{itemID}.json:
get:
summary: Lightspeed Get Item by ID
operationId: getItemById
description: Returns a single inventory item by its itemID.
tags: [Item]
security:
- OAuth2: [employee:inventory_read]
parameters:
- $ref: '#/components/parameters/accountID'
- $ref: '#/components/parameters/itemID'
responses:
'200':
description: The item.
content:
application/json:
schema:
type: object
properties:
Item:
$ref: '#/components/schemas/Item'
examples:
GetItemById200Example:
summary: Default getItemById 200 response
x-microcks-default: true
value:
Item:
itemID: '500123'
systemSku: SKU-1001
defaultCost: '12.50'
avgCost: '12.50'
description: example
upc: example
ean: example
customSku: SKU-1001
manufacturerSku: SKU-1001
categoryID: '500123'
manufacturerID: '500123'
archived: true
Prices: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
put:
summary: Lightspeed Update Item
operationId: updateItem
description: Updates an existing inventory item.
tags: [Item]
security:
- OAuth2: [employee:inventory]
parameters:
- $ref: '#/components/parameters/accountID'
- $ref: '#/components/parameters/itemID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
examples:
UpdateItemRequestExample:
summary: Default updateItem request
x-microcks-default: true
value:
itemID: '500123'
systemSku: SKU-1001
defaultCost: '12.50'
avgCost: '12.50'
description: example
upc: example
ean: example
customSku: SKU-1001
manufacturerSku: SKU-1001
categoryID: '500123'
manufacturerID: '500123'
archived: true
Prices: {}
responses:
'200':
description: Item updated.
content:
application/json:
schema:
type: object
properties:
Item:
$ref: '#/components/schemas/Item'
examples:
UpdateItem200Example:
summary: Default updateItem 200 response
x-microcks-default: true
value:
Item:
itemID: '500123'
systemSku: SKU-1001
defaultCost: '12.50'
avgCost: '12.50'
description: example
upc: example
ean: example
customSku: SKU-1001
manufacturerSku: SKU-1001
categoryID: '500123'
manufacturerID: '500123'
archived: false
Prices: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
summary: Lightspeed Delete Item
operationId: deleteItem
description: Archives (deletes) an inventory item.
tags: [Item]
security:
- OAuth2: [employee:inventory]
parameters:
- $ref: '#/components/parameters/accountID'
- $ref: '#/components/parameters/itemID'
responses:
'204':
description: Item archived.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Sale.json:
get:
summary: Lightspeed List Sales
operationId: getSales
description: Returns point-of-sale transactions for the account.
tags: [Sale]
security:
- OAuth2: [employee:reports]
parameters:
- $ref: '#/components/parameters/accountID'
- name: completed
in: query
description: Filter by completion status.
schema:
type: boolean
- name: limit
in: query
schema:
type: integer
default: 100
responses:
'200':
description: A page of sales.
content:
application/json:
schema:
type: object
properties:
'@attributes':
$ref: '#/components/schemas/Attributes'
Sale:
type: array
items:
$ref: '#/components/schemas/Sale'
examples:
GetSales200Example:
summary: Default getSales 200 response
x-microcks-default: true
value:
'@attributes':
count: 902
offset: 1000
limit: 426
Sale:
- saleID: '500123'
timeStamp: '2026-03-15T14:30:00Z'
completed: true
total: '12.50'
totalDue: '12.50'
displayableTotal: '12.50'
discountPercent: example
customerID: '500123'
employeeID: '500123'
shopID: '500123'
registerID: '500123'
SaleLines:
SaleLine: []
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: Lightspeed Create Sale
operationId: createSale
description: Creates a new sale transaction.
tags: [Sale]
security:
- OAuth2: [employee:register]
parameters:
- $ref: '#/components/parameters/accountID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Sale'
examples:
CreateSaleRequestExample:
summary: Default createSale request
x-microcks-default: true
value:
saleID: '500123'
timeStamp: '2026-03-15T14:30:00Z'
completed: false
total: '12.50'
totalDue: '12.50'
displayableTotal: '12.50'
discountPercent: example
customerID: '500123'
employeeID: '500123'
shopID: '500123'
registerID: '500123'
SaleLines:
SaleLine:
- {}
responses:
'200':
description: Sale created.
content:
application/json:
schema:
type: object
properties:
Sale:
$ref: '#/components/schemas/Sale'
examples:
CreateSale200Example:
summary: Default createSale 200 response
x-microcks-default: true
value:
Sale:
saleID: '500123'
timeStamp: '2026-03-15T14:30:00Z'
completed: false
total: '12.50'
totalDue: '12.50'
displayableTotal: '12.50'
discountPercent: example
customerID: '500123'
employeeID: '500123'
shopID: '500123'
registerID: '500123'
SaleLines:
SaleLine:
- {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Sale/{saleID}.json:
get:
summary: Lightspeed Get Sale by ID
operationId: getSaleById
description: Returns a single sale by its saleID, including its sale lines.
tags: [Sale]
security:
- OAuth2: [employee:reports]
parameters:
- $ref: '#/components/parameters/accountID'
- $ref: '#/components/parameters/saleID'
responses:
'200':
description: The sale.
content:
application/json:
schema:
type: object
properties:
Sale:
$ref: '#/components/schemas/Sale'
examples:
GetSaleById200Example:
summary: Default getSaleById 200 response
x-microcks-default: true
value:
Sale:
saleID: '500123'
timeStamp: '2026-03-15T14:30:00Z'
completed: true
total: '12.50'
totalDue: '12.50'
displayableTotal: '12.50'
discountPercent: example
customerID: '500123'
employeeID: '500123'
shopID: '500123'
registerID: '500123'
SaleLines:
SaleLine:
- {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Customer.json:
get:
summary: Lightspeed List Customers
operationId: getCustomers
description: Returns customer records for the account.
tags: [Customer]
security:
- OAuth2: [employee:customers_read]
parameters:
- $ref: '#/components/parameters/accountID'
- name: limit
in: query
schema:
type: integer
default: 100
responses:
'200':
description: A page of customers.
content:
application/json:
schema:
type: object
properties:
'@attributes':
$ref: '#/components/schemas/Attributes'
Customer:
type: array
items:
$ref: '#/components/schemas/Customer'
examples:
GetCustomers200Example:
summary: Default getCustomers 200 response
x-microcks-default: true
value:
'@attributes':
count: 739
offset: 994
limit: 647
Customer:
- customerID: '500123'
firstName: Sample firstName
lastName: Sample lastName
company: example
contactID: '500123'
discountID: '500123'
taxCategoryID: '500123'
Contact: {}
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
summary: Lightspeed Create Customer
operationId: createCustomer
description: Creates a new customer record.
tags: [Customer]
security:
- OAuth2: [employee:customers]
parameters:
- $ref: '#/components/parameters/accountID'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
examples:
CreateCustomerRequestExample:
summary: Default createCustomer request
x-microcks-default: true
value:
customerID: '500123'
firstName: Sample firstName
lastName: Sample lastName
company: example
contactID: '500123'
discountID: '500123'
taxCategoryID: '500123'
Contact:
contactID: '500123'
custom: example
noEmail: true
noPhone: true
noMail: true
responses:
'200':
description: Customer created.
content:
application/json:
schema:
type: object
properties:
Customer:
$ref: '#/components/schemas/Customer'
examples:
CreateCustomer200Example:
summary: Default createCustomer 200 response
x-microcks-default: true
value:
Customer:
customerID: '500123'
firstName: Sample firstName
lastName: Sample lastName
company: example
contactID: '500123'
discountID: '500123'
taxCategoryID: '500123'
Contact:
contactID: '500123'
custom: example
noEmail: true
noPhone: true
noMail: false
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Customer/{customerID}.json:
get:
summary: Lightspeed Get Customer by ID
operationId: getCustomerById
description: Returns a single customer by its customerID.
tags: [Customer]
security:
- OAuth2: [employee:customers_read]
parameters:
- $ref: '#/components/parameters/accountID'
- $ref: '#/components/parameters/customerID'
responses:
'200':
description: The customer.
content:
application/json:
schema:
type: object
properties:
Customer:
$ref: '#/components/schemas/Customer'
examples:
GetCustomerById200Example:
summary: Default getCustomerById 200 response
x-microcks-default: true
value:
Customer:
customerID: '500123'
firstName: Sample firstName
lastName: Sample lastName
company: example
contactID: '500123'
discountID: '500123'
taxCategoryID: '500123'
Contact:
contactID: '500123'
custom: example
noEmail: false
noPhone: true
noMail: true
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Category.json:
get:
summary: Lightspeed List Categories
operationId: getCategories
description: Returns the item categories defined for the account.
tags: [Catalog]
security:
- OAuth2: [employee:inventory_read]
parameters:
- $ref: '#/components/parameters/accountID'
responses:
'200':
description: A page of categories.
content:
application/json:
schema:
type: object
properties:
Category:
type: array
items:
$ref: '#/components/schemas/Category'
examples:
GetCategories200Example:
summary: Default getCategories 200 response
x-microcks-default: true
value:
Category:
- categoryID: '500123'
name: Sample name
parentID: '500123'
fullPathName: Sample fullPathName
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Manufacturer.json:
get:
summary: Lightspeed List Manufacturers
operationId: getManufacturers
description: Returns the manufacturers defined for the account.
tags: [Catalog]
security:
- OAuth2: [employee:inventory_read]
parameters:
- $ref: '#/components/parameters/accountID'
responses:
'200':
description: A page of manufacturers.
content:
application/json:
schema:
type: object
properties:
Manufacturer:
type: array
items:
$ref: '#/components/schemas/Manufacturer'
examples:
GetManufacturers200Example:
summary: Default getManufacturers 200 response
x-microcks-default: true
value:
Manufacturer:
- manufacturerID: '500123'
name: Sample name
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Vendor.json:
get:
summary: Lightspeed List Vendors
operationId: getVendors
description: Returns the vendors (suppliers) defined for the account.
tags: [Catalog]
security:
- OAuth2: [employee:inventory_read]
parameters:
- $ref: '#/components/parameters/accountID'
responses:
'200':
description: A page of vendors.
content:
application/json:
schema:
type: object
properties:
Vendor:
type: array
items:
$ref: '#/components/schemas/Vendor'
examples:
GetVendors200Example:
summary: Default getVendors 200 response
x-microcks-default: true
value:
Vendor:
- vendorID: '500123'
name: Sample name
accountNumber: example
contactID: '500123'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Employee.json:
get:
summary: Lightspeed List Employees
operationId: getEmployees
description: Returns the employees for the account.
tags: [Staff]
security:
- OAuth2: [employee:admin]
parameters:
- $ref: '#/components/parameters/accountID'
responses:
'200':
description: A page of employees.
content:
application/json:
schema:
type: object
properties:
Employee:
type: array
items:
$ref: '#/components/schemas/Employee'
examples:
GetEmployees200Example:
summary: Default getEmployees 200 response
x-microcks-default: true
value:
Employee:
- employeeID: '500123'
firstName: Sample firstName
lastName: Sample lastName
shopID: '500123'
limitToShopID: '500123'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/Account/{accountID}/Shop.json:
get:
summary: Lightspeed List Shops
operationId: getShops
description: Returns the shops (store locations) for the account.
tags: [Staff]
security:
- OAuth2: [employee:admin]
parameters:
- $ref: '#/components/parameters/accountID'
responses:
'200':
description: A page of shops.
content:
application/json:
schema:
type: object
properties:
Shop:
type: array
items:
$ref: '#/components/schemas/Shop'
examples:
GetShops200Example:
summary: Default getShops 200 response
x-microcks-default: true
value:
Shop:
- shopID: '500123'
name: Sample name
taxCategoryID: '500123'
timeZone: example
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
parameters:
accountID:
name: accountID
in: path
required: true
description: The numeric Lightspeed Retail account identifier, resolved via GET /Account.json.
schema:
type: string
itemID:
name: itemID
in: path
required: true
description: The unique identifier of the item.
schema:
type: string
saleID:
name: saleID
in: path
required: true
description: The unique identifier of the sale.
schema:
type: string
customerID:
name: customerID
in: path
required: true
description: The unique identifier of the customer.
schema:
type: string
securitySchemes:
OAuth2:
type: oauth2
description: OAuth 2.0 authorization-code flow with scope-based access control.
flows:
authorizationCode:
authorizationUrl: https://cloud.lightspeedapp.com/oauth/authorize.php
tokenUrl: https://cloud.lightspeedapp.com/oauth/access_token.php
scopes:
employee:all: Full access to all account resources.
employee:admin: Manage employees and shops.
employee:inventory: Create and modify inventory items.
employee:inventory_read: Read inventory items and catalog.
employee:register: Create sales at the register.
employee:reports: Read sales and reporting data.
employee:customers: Create and modify customers.
employee:customers_read: Read customers.
schemas:
Attributes:
type: object
description: Pagination metadata returned in list responses.
properties:
count:
type: integer
description: Total number of matching records.
offset:
type: integer
description: Offset of the current page.
limit:
type: integer
description: Page size limit.
Account:
type: object
description: A Lightspeed Retail R-Series account.
properties:
accountID:
type: string
description: Unique numeric account identifier.
name:
type: string
description: Account / business name.
link:
type: string
description: API self-link for the account.
Item:
type: object
description: An inventory item sold and tracked in Lightspeed Retail.
properties:
itemID:
type: string
description: Unique item identifier.
systemSku:
type: string
description: System-assigned SKU.
defaultCost:
type: string
description: Default cost of the item.
avgCost:
type: string
description: Weighted average cost.
description:
type: string
description: Item description / name.
upc:
type: string
description: Universal Product Code.
ean:
type: string
description: International Article Number.
customSku:
type: string
description: Merchant-defined SKU.
manufacturerSku:
type: string
description: Manufacturer SKU.
categoryID:
type: string
description: Identifier of the owning category.
manufacturerID:
type: string
description: Identifier of the manufacturer.
archived:
type: boolean
description: Whether the item has been archived.
Prices:
type: object
description: Item pricing levels.
Sale:
type: object
description: A point-of-sale transaction.
properties:
saleID:
type: string
description: Unique sale identifier.
timeStamp:
type: string
format: date-time
description: When the sale occurred.
completed:
type: boolean
description: Whether the sale has been completed.
total:
type: string
description: Sale total including tax.
totalDue:
type: string
description: Amount still owed on the sale.
displayableTotal:
type: string
description: Human-readable total.
discountPercent:
type: string
description: Sale-level discount percentage.
customerID:
type: string
description: Identifier of the customer on the sale.
employeeID:
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightspeed-pos/refs/heads/main/openapi/lightspeed-pos-retail-r-series-openapi.yml