Getting Started with Service Orders

⚠️ Only available with the Service Orders module enabled.

The Service Orders API provides a dedicated endpoint for creating service orders with a customer, a service item, notes and location. For each service order created, a corresponding sale is created behind the scenes.

Create Service Endpoint

POST https://<<domain_prefix>>.retail.lightspeed.app/api/2.0/services

Authentication

This endpoint requires a valid access token with appropriate permissions to create service orders.

Request Payload

The payload must contain the following mandatory attributes:

outlet_id - The outlet of the service
register_id - The register of the service
customer_id - The customer associated with the service

The following attributes are optional:

assigned_user_id - The user assigned to work on the service order
item - The service item and its details
extra_fields - Additional fields for the service order
status - The status of the service order (defaults to "NEW")

Basic Service Creation

{
  "outlet_id": "348fff91-8c43-4599-812b-13636760895a",
  "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
  "customer_id": "06e35f89-3783-11e6-ec7e-13193f7bd2ed"
}

Full Service Creation

{
  "outlet_id": "348fff91-8c43-4599-812b-13636760895a",
  "register_id": "b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4",
  "customer_id": "06e35f89-3783-11e6-ec7e-13193f7bd2ed",
  "assigned_user_id": "b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4",
  "status": "NEW",
  "item": {
    "item_id": "06e35f89-3783-11e6-ec7e-13193f7bd2ed",
    "item_name": "Mountain Bike",
    "serial_number": "MB2025-001",
    "description": "Red mountain bike requiring brake service",
    "initial_condition": "Brakes not functioning properly"
  },
  "extra_fields": {
    "note": "Bike ready for weekend trip",
    "location": "Service Bay 2"
  }
}

Responses

For sucessful and error responses, visit the full documentation.

Definitions

The Service Creation Object

Attribute	Sample Value	Req/Opt	Description
`outlet_id`	`"348fff91-8c43-4599-812b-13636760895a"`	required	ID of the outlet of the service.
`register_id`	`"b1e198a9-f019-11e3-a0f5-b8ca3a64f8f4"`	required	ID of the register of the service.
`customer_id`	`"06e35f89-3783-11e6-ec7e-13193f7bd2ed"`	required	Customer ID associated with the service.
`assigned_user_id`	`"b1ed6158-f019-11e3-a0f5-b8ca3a64f8f4"`	optional	ID of the user assigned to work on the service order.
`status`	`"NEW"`	optional	Status of the service order (defaults to "NEW").
`extra_fields`	See below	optional	Additional fields that can be included with the service order.
`item`	See below	optional	Service item and its details.

The `extra_fields` Object

Attribute	Sample Value	Req/Opt	Description
`note`	`"Customer needs bike ready for weekend trip"`	optional	Note for the service order.
`location`	`"Service Bay 2"`	optional	Location where the item is stored or service will be performed.

The `item` Object

Creating service orders with existing items

Attribute	Sample Value	Req/Opt	Description
`item_id`	`"06e35f89-3783-11e6-ec7e-13193f7bd2ed"`	optional	`id` of an already existing item.
`item_name`	`"Mountain Bike"`	optional	Item name
`serial_number`	`"MB2025-001"`	optional	Item serial number
`description`	`"Red mountain bike requiring brake service"`	optional	Item description
`initial_condition`	`"Brakes not functioning properly"`	optional	Item's initial condition

Important: If you provide an item_id in the item object, the service order will be associated with that existing item and it will behave like a PUT operation: any missing field in the item object will be emptied for that existing item.

By not providing an item_id in the item object, a new service item will be created with the given information (name, serial number, description, etc).