# 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 Sales API
  version: 1.0.0
extends: openapi/lightspeed-sales-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: 5
- target: $.paths['/sales'].get
  update:
    x-apievangelist-phrasing:
      intent: List sales
      effect: read
      questions:
      - What sales has my store made recently?
      - Can I page backwards through older sales?
      instructions:
      - text: List my store's sales.
      - text: Show {size} sales recorded before sale {before}.
        slots:
          size: query.page_size
          before: query.before
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sales'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a new sale
      effect: write
      questions:
      - How do I push an order from my own system into the POS as a sale?
      - Can I create a sale that is saved as a layby or left open rather than closed?
      instructions:
      - text: Create a sale from source {source} in state {state}.
        slots:
          source: requestBody.source
          state: requestBody.state
      - text: Record a {state} sale from {source} for customer {customer} with line items {items}.
        slots:
          state: requestBody.state
          source: requestBody.source
          customer: requestBody.customer_id
          items: requestBody.line_items
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sales/{sale_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a sale
      effect: read
      questions:
      - What was sold and paid on a specific sale?
      - Can I retrieve one sale with its line items and payments?
      instructions:
      - text: Get sale {sale}.
        slots:
          sale: path.sale_id
      - text: Show the line items and payments of sale {sale}.
        slots:
          sale: path.sale_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sales/{sale_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing sale
      effect: write
      questions:
      - Can I add a payment or change the customer on a sale that's already recorded?
      - How do I change the state of an existing sale, say from saved to closed?
      instructions:
      - text: Update sale {sale} to state {state} with source {source}.
        slots:
          sale: path.sale_id
          state: requestBody.state
          source: requestBody.source
      - text: Attach customer {customer} to sale {sale}, keeping source {source} and state {state}.
        slots:
          customer: requestBody.customer_id
          sale: path.sale_id
          source: requestBody.source
          state: requestBody.state
      method: generated
      generated: '2026-09-26'
- target: $.paths['/sales/{sale_id}/actions/return'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a return for a sale
      effect: write
      questions:
      - How do I process a customer return against a closed sale?
      - What does starting a return create before I add the refund?
      instructions:
      - text: Start a return for sale {sale}.
        slots:
          sale: path.sale_id
      - text: Open a return sale against closed sale {sale}.
        slots:
          sale: path.sale_id
      method: generated
      generated: '2026-09-26'