# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for 2026-07 Service Orders API
  version: 1.0.0
extends: openapi/lightspeed-service-orders-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 10
- target: $.paths['/service_items/customer/{customer_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: List a customer's service items
      effect: read
      questions:
      - Which items has a customer brought in for repair or service?
      - Can I page through the service items tied to one customer?
      instructions:
      - text: List the service items for customer {customer}.
        slots:
          customer: path.customer_id
      - text: Show up to {limit} service items for customer {customer}.
        slots:
          limit: query.limit
          customer: path.customer_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/service_statuses'].get
  update:
    x-apievangelist-phrasing:
      intent: List service order statuses
      effect: read
      questions:
      - What statuses can a service order move through in my store?
      - Can I see both the default and my custom service statuses?
      instructions:
      - text: List all service statuses.
      - text: Show my custom and system service order statuses.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/service_statuses'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom service status
      effect: write
      questions:
      - How do I add a custom stage like 'Waiting for parts' to service orders?
      - Where does a newly created service status appear in the display order?
      instructions:
      - text: Create a service status called {name}.
        slots:
          name: requestBody.name
      - text: Add custom service order status {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/service_statuses/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service status
      effect: read
      questions:
      - What are the details of one service status?
      - Can I check whether a service status is a system default or a custom one?
      instructions:
      - text: Get service status {id}.
        slots:
          id: path.id
      - text: Show me the service order status with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/service_statuses/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom service status
      effect: destructive
      questions:
      - Can I delete a custom service status that is no longer used?
      - Why can't a service status be deleted while orders still use it?
      instructions:
      - text: Delete service status {id}.
        slots:
          id: path.id
      - text: Remove the custom service order status {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/service_statuses/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename or reorder a service status
      effect: write
      questions:
      - Can I rename a custom service status?
      - How do I move a service status to a different position in the display order?
      instructions:
      - text: Rename service status {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Move service status {id} to display position {order}.
        slots:
          id: path.id
          order: requestBody.display_order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/services'].get
  update:
    x-apievangelist-phrasing:
      intent: List service orders
      effect: read
      questions:
      - What service orders are open across my store?
      - Can I page through all service orders?
      instructions:
      - text: List all service orders.
      - text: Show the next {limit} service orders after {after}.
        slots:
          limit: query.limit
          after: query.after
      method: generated
      generated: '2026-09-26'
- target: $.paths['/services'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a service order
      effect: write
      questions:
      - How do I book a repair job for a customer at the register?
      - Can I assign a staff member and a custom status when creating a service order?
      instructions:
      - text: Create a service order for customer {customer} at outlet {outlet} on register {register}.
        slots:
          customer: requestBody.customer_id
          outlet: requestBody.outlet_id
          register: requestBody.register_id
      - text: Open a service job for customer {customer} at outlet {outlet}, register {register}, assigned to {user}.
        slots:
          customer: requestBody.customer_id
          outlet: requestBody.outlet_id
          register: requestBody.register_id
          user: requestBody.assigned_user_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/services/{service_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a service order
      effect: read
      questions:
      - What is the current state of a particular service order?
      - Can I retrieve one service job with its item and notes?
      instructions:
      - text: Get service order {service}.
        slots:
          service: path.service_id
      - text: Show the details of service job {service}.
        slots:
          service: path.service_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/services_agenda/outlet/{outlet_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an outlet's service agenda
      effect: read
      questions:
      - What service work is scheduled at a store over the next few days?
      - Can the service agenda account for daylight saving in my timezone?
      instructions:
      - text: Show the service agenda for outlet {outlet} starting {start}.
        slots:
          outlet: path.outlet_id
          start: query.start_date
      - text: Get {days} days of service agenda for outlet {outlet} from {start} in timezone {tz}.
        slots:
          days: query.days
          outlet: path.outlet_id
          start: query.start_date
          tz: query.timezone
      method: generated
      generated: '2026-09-26'