# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely Orders API
  version: 1.0.0
extends: openapi/optimizely-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['/commerce/orders/{customerId}/all'].get
  update:
    x-apievangelist-phrasing:
      intent: List all orders for a customer
      effect: read
      questions:
      - How do I get every order a specific customer has placed?
      - Can I pull a customer's complete order list from the commerce service?
      instructions:
      - text: List all orders for customer {customerId}.
        slots:
          customerId: path.customerId
      - text: Show the full order history of customer {customerId}.
        slots:
          customerId: path.customerId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/orders/{orderGroupId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order by its order group id
      effect: read
      questions:
      - How do I retrieve one commerce order using its order group id?
      - What's in a specific order group?
      instructions:
      - text: Get order group {orderGroupId}.
        slots:
          orderGroupId: path.orderGroupId
      - text: Show me the order with order group id {orderGroupId}.
        slots:
          orderGroupId: path.orderGroupId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/commerce/orders/search/{start}/{maxCount}'].get
  update:
    x-apievangelist-phrasing:
      intent: Page through commerce orders
      effect: read
      questions:
      - How do I search commerce orders a page at a time?
      - Can I set a start offset and a maximum count when searching orders?
      instructions:
      - text: Search orders starting at {start}, returning at most {maxCount}.
        slots:
          start: path.start
          maxCount: path.maxCount
      - text: Fetch the first {maxCount} orders from offset {start}.
        slots:
          maxCount: path.maxCount
          start: path.start
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orders'].get
  update:
    x-apievangelist-phrasing:
      intent: Find the storefront user's orders by filters
      effect: read
      questions:
      - How do I find my orders by PO number or status on the storefront?
      - Can I filter storefront order history by date range or order total?
      - Which orders were placed for a VMI location only?
      instructions:
      - text: Find orders with PO number {poNumber}.
        slots:
          poNumber: query.parameter.poNumber
      - text: List my orders with status {status} placed between {fromDate} and {toDate}.
        slots:
          status: query.parameter.status
          fromDate: query.parameter.fromDate
          toDate: query.parameter.toDate
      - text: Show orders containing product {productErpNumber}.
        slots:
          productErpNumber: query.parameter.productErpNumber
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orders/{orderId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a storefront order by order id
      effect: read
      questions:
      - How do I view the lines and totals of one storefront order?
      - Can I look up a single order in order history by its order id?
      instructions:
      - text: Get storefront order {orderId}.
        slots:
          orderId: path.orderId
      - text: Show the lines and shipping for order {orderId}.
        slots:
          orderId: path.orderId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orders/{orderId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a storefront order
      effect: write
      questions:
      - How do I change the status of a storefront order?
      - Can I update the PO number or notes on an existing order?
      instructions:
      - text: Set the status of order {orderId} to {status}.
        slots:
          orderId: path.orderId
          status: requestBody.status
      - text: Update order {orderId} with customer PO {customerPO}.
        slots:
          orderId: path.orderId
          customerPO: requestBody.customerPO
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orders/{orderId}/returns'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a return (RMA) on an order
      effect: write
      questions:
      - How do I request a return authorization for items on an order?
      - Can I add notes explaining why I'm returning part of an order?
      instructions:
      - text: Request a return on order {orderId} for lines {rmaLines}.
        slots:
          orderId: path.orderId
          rmaLines: requestBody.rmaLines
      - text: Submit an RMA for order {orderId} with notes {notes}.
        slots:
          orderId: path.orderId
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orders/shareorder'].post
  update:
    x-apievangelist-phrasing:
      intent: Share an order by email
      effect: write
      questions:
      - How do I email a copy of an order to a colleague?
      - Can I add a subject and message when sharing an order?
      instructions:
      - text: Share order {entityId} by email with {emailTo}.
        slots:
          entityId: requestBody.entityId
          emailTo: requestBody.emailTo
      - text: Email order {entityId} to {emailTo} with subject {subject}.
        slots:
          entityId: requestBody.entityId
          emailTo: requestBody.emailTo
          subject: requestBody.subject
      method: generated
      generated: '2026-09-26'