# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Overview Returns API
  version: 1.0.0
extends: openapi/aftership-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: 16
- target: $.paths['/returns/{return_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a return by return ID
      effect: read
      questions:
      - How do I look up a return using its internal return ID?
      - What's the current status of the return with this return ID?
      instructions:
      - text: Get return {return_id}.
        slots:
          return_id: path.return_id
      - text: Show the details of return ID {return_id}.
        slots:
          return_id: path.return_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/rma/{rma_number}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a return by RMA number
      effect: read
      questions:
      - Can I find a return using the RMA number the customer gave me?
      - What's in the return with this RMA number?
      instructions:
      - text: Get the return with RMA {rma_number}.
        slots:
          rma_number: path.rma_number
      - text: Look up RMA {rma_number}.
        slots:
          rma_number: path.rma_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter returns
      effect: read
      questions:
      - How do I list returns awaiting approval?
      - Can I find all returns from one customer email?
      - Which returns were created for a given order in a date range?
      instructions:
      - text: List returns with approval status {approval_status}.
        slots:
          approval_status: query.approval_status
      - text: Show returns from customer {customer_email}.
        slots:
          customer_email: query.customer_email
      - text: List returns for order {order_name} created after {created_at_min}.
        slots:
          order_name: query.order_name
          created_at_min: query.created_at_min
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a refund return for an order
      effect: write
      questions:
      - How do I open a return on behalf of a customer?
      - Does creating a return through the API support exchanges, or refunds only?
      instructions:
      - text: Create a return for order {order} with items {return_items} refunded to {refund_destination}.
        slots:
          order: requestBody.order
          return_items: requestBody.return_items
          refund_destination: requestBody.refund_destination
      - text: Open a return on order {order} for {return_items} using method {return_method} and refund to {refund_destination}.
        slots:
          order: requestBody.order
          return_items: requestBody.return_items
          return_method: requestBody.return_method
          refund_destination: requestBody.refund_destination
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/rma/{rma_number}/approve'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve a return by RMA number
      effect: write
      questions:
      - Can I approve a return using its RMA number and generate a label?
      - How do I approve an RMA and email the customer?
      instructions:
      - text: Approve RMA {rma_number}.
        slots:
          rma_number: path.rma_number
      - text: Approve the return with RMA {rma_number} and generate a return label.
        slots:
          rma_number: path.rma_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/{return_id}/approve'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve a return by return ID
      effect: write
      questions:
      - How do I approve a return when I have its return ID?
      - Can approving a return by ID also create the shipping label?
      instructions:
      - text: Approve return ID {return_id}.
        slots:
          return_id: path.return_id
      - text: Approve return {return_id}, generate a label and notify the customer.
        slots:
          return_id: path.return_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/rma/{rma_number}/resolve'].post
  update:
    x-apievangelist-phrasing:
      intent: Resolve a return by RMA number
      effect: write
      questions:
      - Can I resolve a return using the RMA number once it's handled?
      - How do I close an RMA after refunding it?
      instructions:
      - text: Resolve RMA {rma_number}.
        slots:
          rma_number: path.rma_number
      - text: Mark the return with RMA {rma_number} resolved and tell the customer.
        slots:
          rma_number: path.rma_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/{return_id}/resolve'].post
  update:
    x-apievangelist-phrasing:
      intent: Resolve a return by return ID
      effect: write
      questions:
      - How do I move a return to resolved status using its return ID?
      - Can I resolve a return by ID without notifying the shopper?
      instructions:
      - text: Resolve return ID {return_id}.
        slots:
          return_id: path.return_id
      - text: Mark return {return_id} as resolved.
        slots:
          return_id: path.return_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/rma/{rma_number}/reject'].post
  update:
    x-apievangelist-phrasing:
      intent: Reject a return by RMA number
      effect: destructive
      questions:
      - Can I reject a return request using its RMA number?
      - How do I decline an RMA and give a reason?
      instructions:
      - text: Reject RMA {rma_number} because {reject_reason}.
        slots:
          rma_number: path.rma_number
          reject_reason: requestBody.reject_reason
      - text: Decline the return with RMA {rma_number}, reason {reject_reason}.
        slots:
          rma_number: path.rma_number
          reject_reason: requestBody.reject_reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/{return_id}/reject'].post
  update:
    x-apievangelist-phrasing:
      intent: Reject a return by return ID
      effect: destructive
      questions:
      - How do I reject a return when I have its return ID?
      - Can I notify the customer when I reject a return by ID?
      instructions:
      - text: Reject return ID {return_id} because {reject_reason}.
        slots:
          return_id: path.return_id
          reject_reason: requestBody.reject_reason
      - text: Decline return {return_id} with the reason {reject_reason} and notify the customer.
        slots:
          return_id: path.return_id
          reject_reason: requestBody.reject_reason
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/rma/{rma_number}/receive-items'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive returned items by RMA number
      effect: write
      questions:
      - How do I mark returned goods as received in the warehouse using the RMA?
      - Can I receive only some items on an RMA?
      instructions:
      - text: Receive items {items} for RMA {rma_number}.
        slots:
          items: requestBody.items
          rma_number: path.rma_number
      - text: Log that RMA {rma_number}'s items {items} arrived at the warehouse.
        slots:
          rma_number: path.rma_number
          items: requestBody.items
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/{return_id}/receive-items'].post
  update:
    x-apievangelist-phrasing:
      intent: Receive returned items by return ID
      effect: write
      questions:
      - How do I record received return items against a return ID?
      - Which item ID do I use when receiving items on a return by ID?
      instructions:
      - text: Receive items {items} for return ID {return_id}.
        slots:
          items: requestBody.items
          return_id: path.return_id
      - text: Mark items {items} on return {return_id} as received.
        slots:
          items: requestBody.items
          return_id: path.return_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/rma/{rma_number}/attach-shipments'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a return shipment by RMA number
      effect: write
      questions:
      - Can I upload my own return tracking to an RMA?
      - How do I attach a shipment to a return using its RMA number?
      instructions:
      - text: Attach shipment {shipments} to RMA {rma_number}.
        slots:
          shipments: requestBody.shipments
          rma_number: path.rma_number
      - text: Add my own return tracking {shipments} to the return with RMA {rma_number}.
        slots:
          shipments: requestBody.shipments
          rma_number: path.rma_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/{return_id}/attach-shipments'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach a return shipment by return ID
      effect: write
      questions:
      - How do I attach a return shipment when I have the return ID?
      - Can more than one shipment be attached to a return?
      instructions:
      - text: Attach shipment {shipments} to return ID {return_id}.
        slots:
          shipments: requestBody.shipments
          return_id: path.return_id
      - text: Upload tracking {shipments} to return {return_id}.
        slots:
          shipments: requestBody.shipments
          return_id: path.return_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/{return_id}/remove-items'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove items from a return by return ID
      effect: destructive
      questions:
      - What if a shopper no longer wants to return every item on a return?
      - How do I drop items from a return using the return ID?
      instructions:
      - text: Remove items {items} from return ID {return_id} because {edit_reason}.
        slots:
          items: requestBody.items
          return_id: path.return_id
          edit_reason: requestBody.edit_reason
      - text: Take {items} off return {return_id}, reason {edit_reason}, notify customer {notify_customer}.
        slots:
          items: requestBody.items
          return_id: path.return_id
          edit_reason: requestBody.edit_reason
          notify_customer: requestBody.notify_customer
      method: generated
      generated: '2026-09-26'
- target: $.paths['/returns/rma/{rma_number}/remove-items'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove items from a return by RMA number
      effect: destructive
      questions:
      - Can I remove items from a return using its RMA number?
      - How do I shrink an RMA when the customer changes their mind?
      instructions:
      - text: Remove items {items} from RMA {rma_number} because {edit_reason}.
        slots:
          items: requestBody.items
          rma_number: path.rma_number
          edit_reason: requestBody.edit_reason
      - text: Take {items} off RMA {rma_number}, reason {edit_reason}, notify customer {notify_customer}.
        slots:
          items: requestBody.items
          rma_number: path.rma_number
          edit_reason: requestBody.edit_reason
          notify_customer: requestBody.notify_customer
      method: generated
      generated: '2026-09-26'