# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for VirtoCommerce.Return Returns API
  version: 1.0.0
extends: openapi/virto-commerce-returns-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['/api/return/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search product returns
      effect: read
      questions:
      - Which returns have been opened against a particular order?
      - How do I page through all the product returns in my Virto Commerce store?
      - Can I search returns by keyword and sort the results?
      instructions:
      - text: Find all returns filed for order {orderId}.
        slots:
          orderId: requestBody.orderId
      - text: Search returns matching {keyword}.
        slots:
          keyword: requestBody.keyword
      - text: Show me the latest 20 product returns.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/return/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a return by its ID
      effect: read
      questions:
      - What status and resolution does a specific return have?
      - Can I see the line items on one return record?
      instructions:
      - text: Open return {id} and show its line items and status.
        slots:
          id: path.id
      - text: Get the resolution recorded on return {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/return'].put
  update:
    x-apievangelist-phrasing:
      intent: Save or update a product return
      effect: write
      questions:
      - How do I change the status of an existing return?
      - Can I record a resolution on a customer's return?
      - What do I send to save return line items for an order?
      instructions:
      - text: Set the status of return {id} to {status}.
        slots:
          id: requestBody.id
          status: requestBody.status
      - text: Record resolution {resolution} on return {id}.
        slots:
          resolution: requestBody.resolution
          id: requestBody.id
      - text: Save a return for order {orderId} with the returned line items.
        slots:
          orderId: requestBody.orderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/return'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete product returns
      effect: destructive
      questions:
      - How do I remove return records I no longer need?
      - Can I delete several returns at once?
      instructions:
      - text: Delete the returns with IDs {ids}.
        slots:
          ids: query.ids
      - text: Remove return record {ids} permanently.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/return/available-quantities/{orderId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check quantities still returnable on an order
      effect: read
      questions:
      - How many units of each item on an order can still be returned?
      - What quantities are left available to return after earlier returns?
      instructions:
      - text: Show the quantities still available to return on order {orderId}.
        slots:
          orderId: path.orderId
      - text: Check what is left to return from order {orderId}.
        slots:
          orderId: path.orderId
      method: generated
      generated: '2026-09-26'