# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Sendcloud Returns API
  version: 1.0.0
extends: openapi/sendcloud-returns-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/addresses/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a shipping address
      effect: read
      questions:
      - Can I check that a shipping address is valid before I create a label?
      - Which carrier do I need to name when checking an address for deliverability?
      instructions:
      - text: Validate the address {address} for carrier {carrier_code}.
        slots:
          address: requestBody.address
          carrier_code: requestBody.carrier_code
      - text: Check whether {address} is a deliverable address before shipping with {carrier_code}.
        slots:
          address: requestBody.address
          carrier_code: requestBody.carrier_code
      method: generated
      generated: '2026-10-01'
- target: $.paths['/returns'].get
  update:
    x-apievangelist-phrasing:
      intent: List returns
      effect: read
      questions:
      - Which returns were created in the last two weeks?
      - Can I filter returns by the status of the original parcel?
      instructions:
      - text: List returns from {from_date} to {to_date}.
        slots:
          from_date: query.from_date
          to_date: query.to_date
      - text: Show returns between {from_date} and {to_date} with parent status {parent_parcel_status}.
        slots:
          from_date: query.from_date
          to_date: query.to_date
          parent_parcel_status: query.parent_parcel_status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/returns'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a return
      effect: write
      questions:
      - How do I create a standalone return for a customer?
      - Can I send tracking emails to the customer when creating a return?
      instructions:
      - text: Create a return from {from_address} to {to_address} weighing {weight} with {ship_with}.
        slots:
          from_address: requestBody.from_address
          to_address: requestBody.to_address
          weight: requestBody.weight
          ship_with: requestBody.ship_with
      - text: Create a return for order {order_number} from {from_address}.
        slots:
          order_number: requestBody.order_number
          from_address: requestBody.from_address
      method: generated
      generated: '2026-10-01'
- target: $.paths['/returns/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a return
      effect: read
      questions:
      - How do I check the details of a specific return?
      - What's the status of one return parcel?
      instructions:
      - text: Show return {id}.
        slots:
          id: path.id
      - text: Get the details of return {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/returns/{id}/cancel'].patch
  update:
    x-apievangelist-phrasing:
      intent: Request cancellation of a return
      effect: destructive
      questions:
      - Can I cancel a return a customer no longer needs?
      - How do I ask for a return to be cancelled?
      instructions:
      - text: Request cancellation of return {id}.
        slots:
          id: path.id
      - text: Cancel return {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/returns/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a return can be announced
      effect: read
      questions:
      - Can I test whether a return would be accepted without creating it?
      - Is there a dry run for returns before announcing to the carrier?
      instructions:
      - text: Validate a return from {from_address} to {to_address} via {ship_with} without creating it.
        slots:
          from_address: requestBody.from_address
          to_address: requestBody.to_address
          ship_with: requestBody.ship_with
      - text: Dry-run a {weight} return from {from_address}.
        slots:
          weight: requestBody.weight
          from_address: requestBody.from_address
      method: generated
      generated: '2026-10-01'
- target: $.paths['/returns/announce-synchronously'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a return and wait for the carrier
      effect: write
      questions:
      - How do I create a return and get the carrier's response immediately?
      - Can I announce a return synchronously instead of in the background?
      instructions:
      - text: Create a return synchronously from {from_address} to {to_address} with {ship_with}.
        slots:
          from_address: requestBody.from_address
          to_address: requestBody.to_address
          ship_with: requestBody.ship_with
      - text: Announce a {weight} return now and wait for the carrier.
        slots:
          weight: requestBody.weight
      method: generated
      generated: '2026-10-01'