Lightspeed Commerce Service Orders API

openapi: 3.2.0
info:
  contact:
    email: x-series.api@lightspeedhq.com
    name: Lightspeed Developer Relations
    url: https://developers.retail.lightspeed.app
  description: Lightspeed Retail (X-Series) API.
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://developers.lightspeedhq.com/terms
  title: 2026-07 Service Orders API
  version: 2026-07
servers:
- url: https://{domain_prefix}.retail.lightspeed.app/api/2026-07
  variables:
    domain_prefix:
      default: example
      description: Domain prefix of the store to be operated on
security:
- bearerAuth: []
tags:
- description: Service orders and Job management
  name: Service Orders
paths:
  /service_items/customer/{customer_id}:
    get:
      description: 'Returns a paginated list of customer''s service items.


        🔒 Requires: `services:read` scope'
      operationId: ListServiceItems
      parameters:
      - description: The customer id
        in: path
        name: customer_id
        required: true
        schema:
          type: string
      - description: The lower limit for the service id to be included in the response. For proper pagination, it needs to be the item id of the last item in the response from your previous request.
        in: query
        name: after
        schema:
          format: int64
          type: integer
      - description: The maximum number of items to be returned in the response.
        in: query
        name: limit
        schema:
          default: 100
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                has_next: false
                job_items:
                - created_at: '2025-08-12T18:46:30.216844Z'
                  created_by: 06e94082-ed4f-11ed-fd41-fef5ad8054af
                  initial_condition: Screen cracked, minor water damage
                  item_details:
                    description: Customer's primary phone with cracked screen
                    serial_number: F2LXN1234A
                  item_id: e6fd369e-e579-4768-b12d-6754af620f2d
                  item_name: iPhone 15 Pro
                  updated_at: '2025-08-12T18:46:30.216844Z'
                  updated_by: 06e94082-ed4f-11ed-fd41-fef5ad8054af
                - created_at: '2025-08-12T18:44:14.387026Z'
                  created_by: 06e94082-ed4f-11ed-fd41-fef5ad8054af
                  initial_condition: Spacebar key not responding consistently
                  item_details:
                    description: 13-inch laptop with keyboard issues
                    serial_number: C02D12345678
                  item_id: a57dc842-1075-458a-ab98-f658c4f985de
                  item_name: MacBook Air M2
                  updated_at: '2025-08-12T18:44:14.387026Z'
                  updated_by: 06e94082-ed4f-11ed-fd41-fef5ad8054af
                total_job_items: 2
              schema:
                properties:
                  has_next:
                    type: boolean
                  job_items:
                    items:
                      properties:
                        created_at:
                          type: string
                        created_by:
                          type: string
                        initial_condition:
                          type: string
                        item_details:
                          properties:
                            description:
                              type: string
                            serial_number:
                              type: string
                          type: object
                        item_id:
                          type: string
                        item_name:
                          type: string
                        updated_at:
                          type: string
                        updated_by:
                          type: string
                      type: object
                    type: array
                  total_job_items:
                    type: integer
                type: object
          description: ''
        '401':
          content:
            application/json:
              example:
                error: Access token is not valid
          description: Unauthorized
      summary: List a customer's service items
      tags:
      - Service Orders
  /service_statuses:
    get:
      description: 'Returns all service statuses for the retailer, including system defaults and custom ones.


        **Only available with the Service Orders module enabled.**


        🔒 Requires: `services:read` scope'
      operationId: ListServiceStatuses
      responses:
        '200':
          content:
            application/json:
              example:
              - created_at: '2026-01-15T10:00:00Z'
                display_name: New
                display_order: 1
                id: '2038696150067306496'
                retailer_id: 00000000-0001-0001-0001-000000000001
                status_key: NEW
                system_default: true
                updated_at: '2026-01-15T10:00:00Z'
              - created_at: '2026-01-15T10:00:00Z'
                display_name: Waiting for Parts
                display_order: 2
                id: '2038696150067306497'
                retailer_id: 00000000-0001-0001-0001-000000000001
                status_key: CUSTOM
                system_default: false
                updated_at: '2026-01-15T10:00:00Z'
              schema:
                items:
                  $ref: '#/components/schemas/ServiceStatusDetails'
                type: array
          description: List of service statuses
        '401':
          content:
            application/json:
              example:
                error: Access token is not valid
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                error: user missing required permissions
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Forbidden — missing `services:read` scope
      summary: List service statuses
      tags:
      - Service Orders
    post:
      description: 'Creates a new custom service status for the retailer. The new status is

        appended at the end of the display order. Use the PATCH endpoint to

        change its position after creation.


        **Only available with the Service Orders module enabled.**


        🔒 Requires: `services:write` scope'
      operationId: CreateServiceStatus
      requestBody:
        content:
          application/json:
            schema:
              properties:
                name:
                  description: Human-readable name for the status.
                  type: string
              required:
              - name
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                created_at: '2026-03-31T18:23:47.719422Z'
                display_name: Waiting for Parts
                display_order: 5
                id: '2039046012672835584'
                retailer_id: 00000000-0001-0001-0001-000000000001
                status_key: CUSTOM
                system_default: false
                updated_at: '2026-03-31T18:23:47.719422Z'
              schema:
                $ref: '#/components/schemas/ServiceStatusDetails'
          description: Service status created successfully
        '400':
          content:
            application/json:
              example:
                error: name cannot be empty
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Bad request — name is missing or blank
        '401':
          content:
            application/json:
              example:
                error: Access token is not valid
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                error: user missing required permissions
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Forbidden — missing `services:write` scope
        '409':
          content:
            application/json:
              example:
                error: a status already exists with this name
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Conflict — a status with this name already exists
      summary: Create a service status
      tags:
      - Service Orders
  /service_statuses/{id}:
    parameters:
    - description: ID of the service status
      in: path
      name: id
      required: true
      schema:
        type: string
    delete:
      description: 'Deletes a custom service status.


        System default statuses cannot be deleted. A status cannot be deleted if it is still assigned to one or more service orders.


        **Only available with the Service Orders module enabled.**


        🔒 Requires: `services:write` scope'
      operationId: DeleteServiceStatus
      responses:
        '204':
          description: Service status deleted successfully
        '401':
          content:
            application/json:
              example:
                error: Access token is not valid
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                error: cannot modify system status
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Forbidden — missing `services:write` scope, or attempting to delete a system default status
        '404':
          content:
            application/json:
              example:
                error: job status not found
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Not Found
        '409':
          content:
            application/json:
              example:
                error: status is in use by one or more jobs and cannot be deleted without a replacement
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Conflict — status is still assigned to one or more service orders
      summary: Delete a service status
      tags:
      - Service Orders
    get:
      description: 'Returns a single service status by ID.


        **Only available with the Service Orders module enabled.**


        🔒 Requires: `services:read` scope'
      operationId: GetServiceStatus
      responses:
        '200':
          content:
            application/json:
              example:
                created_at: '2026-03-30T19:28:37.155851Z'
                display_name: newest custom edited?
                display_order: 4
                id: '2038699938241933312'
                retailer_id: 00000000-0001-0001-0001-000000000001
                status_key: CUSTOM
                system_default: false
                updated_at: '2026-03-31T18:23:07.400648Z'
              schema:
                $ref: '#/components/schemas/ServiceStatusDetails'
          description: Service status found
        '401':
          content:
            application/json:
              example:
                error: Access token is not valid
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                error: user missing required permissions
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Forbidden — missing `services:read` scope
        '404':
          content:
            application/json:
              example:
                error: job status not found
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Not Found
      summary: Get a service status
      tags:
      - Service Orders
    patch:
      description: 'Partially updates a custom service status. Only provided fields are updated.


        System default statuses cannot be modified.


        **Only available with the Service Orders module enabled.**


        🔒 Requires: `services:write` scope'
      operationId: UpdateServiceStatus
      requestBody:
        content:
          application/json:
            schema:
              properties:
                display_order:
                  description: New display order. Can be set to null to clear it.
                  type:
                  - integer
                  - 'null'
                name:
                  description: New human-readable name for the status. If provided, must not be blank.
                  type: string
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              example:
                created_at: '2026-03-30T19:28:37.155851Z'
                display_name: newest custom edited?
                display_order: 4
                id: '2038699938241933312'
                retailer_id: 00000000-0001-0001-0001-000000000001
                status_key: CUSTOM
                system_default: false
                updated_at: '2026-03-31T18:23:07.400648Z'
              schema:
                $ref: '#/components/schemas/ServiceStatusDetails'
          description: Service status updated successfully
        '400':
          content:
            application/json:
              example:
                error: name cannot be empty
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Bad request — name is provided but blank
        '401':
          content:
            application/json:
              example:
                error: Access token is not valid
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                error: cannot modify system status
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Forbidden — missing `services:write` scope, or attempting to modify a system default status
        '404':
          content:
            application/json:
              example:
                error: job status not found
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Not Found
        '409':
          content:
            application/json:
              examples:
                duplicate_display_order:
                  value:
                    error: a status already exists with this display order
                duplicate_name:
                  value:
                    error: a status already exists with this name
              schema:
                properties:
                  error:
                    type: string
                type: object
          description: Conflict — a status with this name or display order already exists
      summary: Update a service status
      tags:
      - Service Orders
  /services:
    get:
      description: 'Returns a paginated list of services.


        🔒 Requires: `services:read` scope'
      operationId: ListServices
      parameters:
      - description: The lower limit for the service id to be included in the response. For proper pagination, it needs to be the service id of the last item in the response from your previous request.
        in: query
        name: after
        schema:
          format: int64
          type: integer
      - description: The maximum number of items to be returned in the response.
        in: query
        name: limit
        schema:
          default: 100
          format: int64
          type: integer
      responses:
        '200':
          content:
            application/json:
              example:
                has_next: false
                jobs:
                - service:
                    agenda:
                      date: '2025-08-27T04:00:00Z'
                      minutes_scheduled: 120
                    assigned_user_id: ''
                    created_at: '2025-08-25T16:26:29.56854Z'
                    id: '1960015938019700736'
                    line_items:
                    - fulfillment_type: UNSPECIFIED
                      gift_card: null
                      id: dc8fcea9-e4eb-47b1-9994-fa7fa8d10f53
                      is_picklist_pickable: false
                      note: ''
                      price_set: false
                      product_id: ced180dd-1234-47ae-b16e-149897b26681
                      promotions: []
                      quantity: '1'
                      register_id: 06e94082-ed4f-11ed-fd41-fef5ad8737fa
                      register_sequence_id: 0698ab21-5f72-11f0-f6d9-785ab008ba49
                      sales_person_id: ''
                      sequence: '0'
                      sku: '10026'
                      state: CONFIRMED
                      tax_components: []
                      unit_discount: '0'
                      unit_loyalty: '0'
                      unit_price: '15'
                    retailer_id: 06e94082-ed4f-11ed-fd41-fef5ad4ffc39
                    sale_id: 6872a358-0089-89ae-11f0-81cfbf9b0ca1
                    status: NEW
                    status_details:
                      created_at: '2025-08-25T16:26:29.56854Z'
                      display_name: New
                      display_order: 1
                      id: '2038696150067306496'
                      retailer_id: 06e94082-ed4f-11ed-fd41-fef5ad4ffc39
                      status_key: NEW
                      system_default: true
                      updated_at: '2025-08-25T16:26:29.56854Z'
                    totals:
                      is_sale_level_discount_percentage: false
                      sale_level_discount_value: '0'
                      sub_total: '15'
                      total_amount: '16.95'
                      total_promotion: '0'
                      total_tax: '1.95'
                    updated_at: '2025-08-25T16:26:29.732308Z'
                  service_item:
                    created_at: '2025-08-21T18:08:14.277021Z'
                    created_by: tech-001
                    initial_condition: Needs new brake pads and general tune-up.
                    item_details:
                      description: 2022 Trek FX 3 Disc, 21-speed hybrid bike, black.
                      serial_number: TREKFX3-2022-12345
                    item_id: bike-001
                    item_name: Trek FX 3 Disc Hybrid Bike
                    updated_at: '2025-08-21T18:08:14.43438Z'
                    updated_by: tech-001
                total_jobs: 1
              schema:
                properties:
                  has_next:
                    description: Whether or not there are more pages available
                    type: boolean
                  jobs:
                    items:
                      properties:
                        service:
                          $ref: '#/components/schemas/ServiceOrder'
                        service_item:
                          type:
                          - object
                          - 'null'
                      type: object
                    type: array
                  total_jobs:
                    description: Total number of jobs
                    type: integer
                type: object
          description: A paginated list of service orders
        '401':
          content:
            application/json:
              example:
                error: Access token is not valid
          description: Unauthorized
      summary: List services
      tags:
      - Service Orders
    post:
      description: '**Only available with the Service Orders module enabled.**


        Creates a new service order. This endpoint allows you to create service orders with a customer, a service item, note and location.


        🔒 Requires: `services:write` `sales:write` scopes'
      operationId: CreateService
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceOrderRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedService'
          description: Service order created successfully
        '400':
          content:
            application/json:
              example:
                error: 'twirp error invalid_argument: register_id register ID can''t be empty'
              schema:
                properties:
                  error:
                    description: Error message describing the bad request
                    type: string
                type: object
          description: Bad request
        '401':
          content:
            application/json:
              example:
                error: CSRF validation fail
              schema:
                properties:
                  error:
                    description: Error message describing the authentication failure
                    type: string
                type: object
          description: Unauthorized
        '403':
          content:
            application/json:
              example:
                error: user missing required permissions
              schema:
                properties:
                  error:
                    description: Error message describing the authorization failure
                    type: string
                type: object
          description: Forbidden
      summary: Create a service order
      tags:
      - Service Orders
  /services/{service_id}:
    parameters:
    - description: ID of the service to get
      in: path
      name: service_id
      required: true
      schema:
        type: string
    get:
      description: 'Get a single service order.


        🔒 Requires: `services:read` scope'
      operationId: GetService
      responses:
        '200':
          content:
            application/json:
              example:
                notes:
                - body: ''
                  created_at: '2025-08-25T16:26:29.56854Z'
                  created_by: 06e94082-ed4f-11ed-fd41-fef5ad8054af
                  id: '1960015938019700737'
                  service_id: '1960015938019700736'
                  service_status: NEW
                service:
                  agenda:
                    date: '2025-08-27T04:00:00Z'
                    minutes_scheduled: 120
                  assigned_user_id: ''
                  created_at: '2025-08-25T16:26:29.56854Z'
                  id: '1960015938019700736'
                  line_items:
                  - fulfillment_type: UNSPECIFIED
                    gift_card: null
                    id: dc8fcea9-e4eb-47b1-9994-fa7fa8d10f53
                    is_picklist_pickable: false
                    note: ''
                    price_set: false
                    product_id: ced180dd-1234-47ae-b16e-149897b26681
                    promotions: []
                    quantity: '1'
                    register_id: 06e94082-ed4f-11ed-fd41-fef5ad8737fa
                    register_sequence_id: 0698ab21-5f72-11f0-f6d9-785ab008ba49
                    sales_person_id: ''
                    sequence: '0'
                    sku: '10026'
                    state: CONFIRMED
                    tax_components: []
                    unit_discount: '0'
                    unit_loyalty: '0'
                    unit_price: '15'
                  location: 'Bike rack #123'
                  retailer_id: 06e94082-ed4f-11ed-fd41-fef5ad4ffc39
                  sale_id: 6872a358-0089-89ae-11f0-81cfbf9b0ca1
                  status: NEW
                  status_details:
                    created_at: '2025-08-25T16:26:29.56854Z'
                    display_name: New
                    display_order: 1
                    id: '2038696150067306496'
                    retailer_id: 06e94082-ed4f-11ed-fd41-fef5ad4ffc39
                    status_key: NEW
                    system_default: true
                    updated_at: '2025-08-25T16:26:29.56854Z'
                  totals:
                    is_sale_level_discount_percentage: false
                    sale_level_discount_value: '0'
                    sub_total: '15'
                    total_amount: '16.95'
                    total_promotion: '0'
                    total_tax: '1.95'
                  updated_at: '2025-08-25T16:26:29.732308Z'
                service_item:
                  created_at: '2025-07-25T23:59:10.335813Z'
                  created_by: 06e94082-ed4f-11ed-fd41-fef5ad8054af
                  initial_condition: Needs new brake pads and general tune-up.
                  item_details:
                    description: 2022 Trek FX 3 Disc, 21-speed hybrid bike, black.
                    serial_number: TREKFX3-2022-12345
                  item_id: f808afa3-c8f6-4b13-aa37-4b90dfae77a5
                  item_name: Trek FX 3 Disc Hybrid Bike
                  updated_at: '2025-08-25T16:26:29.619284Z'
                  updated_by: 662d3131-6434-2d65-3832-303665393430
              schema:
                $ref: '#/components/schemas/DetailedService'
          description: Service has been found
        '401':
          content:
            application/json:
              example:
                error: Access token is not valid
          description: Unauthorized
        '404':
          content:
            application/json:
              example:
                error: service not found
          description: Not Found
      summary: Get service
      tags:
      - Service Orders
  /services_agenda/outlet/{outlet_id}:
    parameters:
    - description: The size, in days, of the time window for which the agenda is requested.
      in: query
      name: days
      schema:
        default: 7
        example: 31
        type: integer
    - description: The first date of the time window for which the agenda is requested.
      in: query
      name: start_date
      required: true
      schema:
        example: '2017-07-21T17:32:28Z'
        format: date-time
        type: string
    - description: The timezone in which the agenda is requested. When provided, the agenda returned will account for time changes like daylight savings.
      in: query
      name: timezone
      schema:
        example: America/New_York
        type: string
    - in: path
      name: outlet_id
      required: true
      schema:
        type: string
    get:
      description: 'Returns the service agenda for the specified outlet within the given time window.


        🔒 Requires: `services:read` scope'
      operationId: get-agenda-outlet_id
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DailyAgenda'
                type: array
          description: Outlet's service agenda
        '401':
          content:
            application/json:
              example:
                error: Access token is not valid
          description: Unauthorized
      summary: Get services agenda by outlet
      tags:
      - Service Orders
components:
  schemas:
    DetailedService:
      properties:
        notes:
          description: An array of service notes, or null if no notes exist.
          items:
            $ref: '#/components/schemas/ServiceNote'
          type:
          - array
          - 'null'
        service:
          $ref: '#/components/schemas/ServiceOrder'
        serviceItems:
          $ref: '#/components/schemas/ServiceItems'
      title: DetailedService
      type: object
      x-stoplight:
        id: 2fu3rgyr0q1gp
    DailyAgenda:
      properties:
        date:
          type: string
        minutes_scheduled:
          type: integer
      title: DailyAgenda
      type: object
    ServiceOrder:
      properties:
        agenda:
          $ref: '#/components/schemas/DailyAgenda'
        assigned_user_id:
          type: string
        created_at:
          type: string
        id:
          type: string
        line_items:
          description: Collection of line items associated with this service order.
          items:
            properties:
              fulfillment_type:
                description: Type of fulfillment for this line item.
                type: string
              gift_card:
                description: Gift card information if applicable.
                type:
                - object
                - 'null'
              id:
                description: The ID of this line item.
                type: string
              is_picklist_pickable:
                description: Indicates if this line item can be picked from a picklist.
                type: boolean
              note:
                description: Line item note.
                type: string
              price_set:
                description: Indicates whether the price was set manually.
                type: boolean
              product_id:
                description: The ID of the product associated with this line item.
                type: string
              promotions:
                description: Array of promotions applied to this line item.
                items:
                  $ref: '#/components/schemas/PromotionDescription'
                type: array
              quantity:
                description: Quantity of products for the line item.
                type: string
              register_id:
                description: The register ID associated with this line item.
                type: string
              register_sequence_id:
                description: The register sequence ID for this line item.
                type: string
              sales_person_id:
                description: The ID of the salesperson associated with this line item.
                type: string
              sequence:
                description: Order of the line item in the service order.
                type: integer
              sku:
                description: The SKU of the product.
                type: string
              state:
                description: State of the line item.
                type: string
              tax_components:
                description: Collection of tax components associated with the line item.
                items:
                  $ref: '#/components/schemas/LineItemTaxComponent'
                type: array
              unit_discount:
                description: Unit discount value for the line item.
                type: string
              unit_loyalty:
                description: Unit loyalty value for the line item.
                type: string
              unit_price:
                description: Unit price of the line item.
                type: string
            type: object
          type: array
        location:
          type: string
        retailer_id:
          type: string
        

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lightspeed/refs/heads/main/openapi/lightspeed-service-orders-api-openapi.yml