# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Square Orders API
  version: 1.0.0
extends: openapi/square-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: 8
- target: $.paths['/v2/orders'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an order
      effect: write
      questions:
      - How do I create an order with line items in Square?
      - Can I apply taxes and discounts when I first create an order?
      instructions:
      - text: Create order {order}.
        slots:
          order: requestBody.order
      - text: 'Start a new order with these line items: {order}.'
        slots:
          order: requestBody.order
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/batch-retrieve'].post
  update:
    x-apievangelist-phrasing:
      intent: Fetch several orders by ID
      effect: read
      questions:
      - Can I pull up many orders at once when I have their IDs?
      - What happens if one of the order IDs I request doesn't exist?
      instructions:
      - text: Get orders {order_ids}.
        slots:
          order_ids: requestBody.order_ids
      - text: Retrieve orders {order_ids} at location {location_id}.
        slots:
          order_ids: requestBody.order_ids
          location_id: requestBody.location_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/calculate'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview order pricing without saving
      effect: read
      questions:
      - How can I preview an order's total, taxes and discounts before creating it?
      - Can I see how a loyalty reward would change an order's price?
      instructions:
      - text: Calculate the totals for order {order}.
        slots:
          order: requestBody.order
      - text: Preview pricing of {order} with proposed rewards {proposed_rewards}.
        slots:
          order: requestBody.order
          proposed_rewards: requestBody.proposed_rewards
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/clone'].post
  update:
    x-apievangelist-phrasing:
      intent: Duplicate an existing order as a draft
      effect: write
      questions:
      - How do I copy an existing order to reorder the same items?
      - Which fields carry over when an order is cloned?
      instructions:
      - text: Clone order {order_id}.
        slots:
          order_id: requestBody.order_id
      - text: Duplicate order {order_id} at version {version} into a new draft.
        slots:
          order_id: requestBody.order_id
          version: requestBody.version
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search orders across locations
      effect: read
      questions:
      - How do I find all orders from last week across my locations?
      - Can I search orders by state, date or customer?
      - Is it possible to return just order IDs instead of full orders when searching?
      instructions:
      - text: Search orders at locations {location_ids} matching {query}.
        slots:
          location_ids: requestBody.location_ids
          query: requestBody.query
      - text: 'Find orders at {location_ids} and return only entries: {return_entries}.'
        slots:
          location_ids: requestBody.location_ids
          return_entries: requestBody.return_entries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/{order_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order
      effect: read
      questions:
      - What items and totals are on a specific order?
      - How do I look up a single order by its ID?
      instructions:
      - text: Get order {order_id}.
        slots:
          order_id: path.order_id
      - text: Show the line items and totals of order {order_id}.
        slots:
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/{order_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an open order
      effect: write
      questions:
      - How do I add or remove items on an order that's still open?
      - Can I update an order after it has been completed or canceled?
      instructions:
      - text: Update order {order_id} with {order}.
        slots:
          order_id: path.order_id
          order: requestBody.order
      - text: Clear fields {fields_to_clear} on open order {order_id}.
        slots:
          fields_to_clear: requestBody.fields_to_clear
          order_id: path.order_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/orders/{order_id}/pay'].post
  update:
    x-apievangelist-phrasing:
      intent: Pay for an order with approved payments
      effect: write
      questions:
      - How do I settle an order using payments I already approved?
      - Can I complete an order whose total is zero?
      instructions:
      - text: Pay order {order_id} with payments {payment_ids}.
        slots:
          order_id: path.order_id
          payment_ids: requestBody.payment_ids
      - text: Settle order {order_id} at version {order_version}.
        slots:
          order_id: path.order_id
          order_version: requestBody.order_version
      method: generated
      generated: '2026-09-26'