# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Toast Orders API
  version: 1.0.0
extends: openapi/toast-orders-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: 8
- target: $.paths['/prices'].post
  update:
    x-apievangelist-phrasing:
      intent: Calculate prices and taxes for an order
      effect: read
      questions:
      - What would the total, tax and service charges be for an order before submitting it?
      - Can I validate an order's pricing without actually placing it?
      instructions:
      - text: Price this order with dining option {dining_option} and checks {checks} at {restaurant}.
        slots:
          dining_option: requestBody.diningOption
          checks: requestBody.checks
          restaurant: header.Toast-Restaurant-External-ID
      - text: Calculate tax and service charges for checks {checks} without placing the order.
        slots:
          checks: requestBody.checks
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orders/{guid}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one order
      effect: read
      questions:
      - Where can I see full details for a single order by its GUID?
      - What information comes back for one specific order?
      instructions:
      - text: Get order {guid} at restaurant {restaurant}.
        slots:
          guid: path.guid
          restaurant: header.Toast-Restaurant-External-ID
      - text: Show me everything on order {guid}.
        slots:
          guid: path.guid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/ordersBulk'].get
  update:
    x-apievangelist-phrasing:
      intent: Get full order details for a time period
      effect: read
      questions:
      - Can I download complete order details for every order opened in a business day?
      - What paging options exist when pulling many orders with full details?
      instructions:
      - text: Get all orders with full details at {restaurant} for business date {date}.
        slots:
          restaurant: header.Toast-Restaurant-External-ID
          date: query.businessDate
      - text: Fetch detailed orders opened between {start} and {end}, page {page}.
        slots:
          start: query.startDate
          end: query.endDate
          page: query.page
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orders/{orderGuid}/checks/{checkGuid}/selections'].post
  update:
    x-apievangelist-phrasing:
      intent: Add items to an existing check
      effect: write
      questions:
      - Is it possible to add more menu items to a check that is already open?
      - Can I append several selections to an existing order's check at once?
      instructions:
      - text: Add these items to check {check} on order {order}.
        slots:
          check: path.checkGuid
          order: path.orderGuid
      - text: Append menu selections to check {check} of order {order} at {restaurant}.
        slots:
          check: path.checkGuid
          order: path.orderGuid
          restaurant: header.Toast-Restaurant-External-ID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orders/{orderGuid}/deliveryInfo'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an order's delivery details
      effect: write
      questions:
      - Can I mark a delivery order as dispatched or delivered?
      - Can I change the driver assigned to a delivery order?
      instructions:
      - text: Set delivery state of order {order} to {state}.
        slots:
          order: path.orderGuid
          state: requestBody.deliveryState
      - text: Assign delivery employee {employee} to order {order} and note {notes}.
        slots:
          employee: requestBody.deliveryEmployee
          order: path.orderGuid
          notes: requestBody.notes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orders/{orderGuid}/void'].post
  update:
    x-apievangelist-phrasing:
      intent: Void an order
      effect: destructive
      questions:
      - How do I void an order along with its items and payments?
      - Which orders are eligible to be voided based on payment type?
      instructions:
      - text: Void order {order} at restaurant {restaurant}.
        slots:
          order: path.orderGuid
          restaurant: header.Toast-Restaurant-External-ID
      - text: Void order {order} including selections {selections} and payments {payments}.
        slots:
          order: path.orderGuid
          selections: requestBody.selections
          payments: requestBody.payments
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: List order GUIDs for a period (deprecated)
      effect: read
      questions:
      - Is there an older endpoint that returns only the GUIDs of orders opened in a time window?
      - What is the longest time span the deprecated order ID list supports?
      instructions:
      - text: List order GUIDs at {restaurant} for business date {date} using the deprecated endpoint.
        slots:
          restaurant: header.Toast-Restaurant-External-ID
          date: query.businessDate
      - text: Get just the order IDs opened between {start} and {end}.
        slots:
          start: query.startDate
          end: query.endDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orders'].post
  update:
    x-apievangelist-phrasing:
      intent: Place a new order
      effect: write
      questions:
      - How do I submit a new order to a restaurant?
      - What does an order need at minimum to be accepted, like dining option and checks?
      instructions:
      - text: Place an order at {restaurant} with dining option {dining_option} and checks {checks}.
        slots:
          restaurant: header.Toast-Restaurant-External-ID
          dining_option: requestBody.diningOption
          checks: requestBody.checks
      - text: Submit a delivery order with checks {checks} and delivery info {delivery}.
        slots:
          checks: requestBody.checks
          delivery: requestBody.deliveryInfo
      method: generated
      generated: '2026-10-01'