# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Admin API V1 Order Histories API
  version: 1.0.0
extends: openapi/optimizely-order-histories-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: 12
- target: $.paths['/api/v1/admin/OrderHistories'].get
  update:
    x-apievangelist-phrasing:
      intent: List historical orders
      effect: read
      questions:
      - How do I pull the order history synced from our ERP into the commerce admin?
      - Can I filter past orders by customer number or status?
      - What guest orders were placed last month?
      instructions:
      - text: List all order history records.
      - text: List order histories matching {filter}, newest first by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      - text: Count the order history records that match {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistories'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a historical order record
      effect: write
      questions:
      - How do I load an order from our ERP into the order history?
      - What bill-to and ship-to fields does a new order history record need?
      instructions:
      - text: Create an order history for ERP order {erpOrderNumber} for customer {customerNumber} with status {status}.
        slots:
          erpOrderNumber: requestBody.erpOrderNumber
          customerNumber: requestBody.customerNumber
          status: requestBody.status
      - text: Add web order {webOrderNumber} with PO {customerPO} to order history.
        slots:
          webOrderNumber: requestBody.webOrderNumber
          customerPO: requestBody.customerPO
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistories({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one historical order
      effect: read
      questions:
      - How do I see the totals and addresses on one past order?
      - Can I expand the lines of a single order history record?
      instructions:
      - text: Get order history {id}.
        slots:
          id: path.id
      - text: Show order history {id} with {expand} expanded.
        slots:
          id: path.id
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistories({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a historical order record
      effect: write
      questions:
      - How do I overwrite a whole order history record with fresh ERP data?
      - Is there a way to fully replace a past order rather than patch it?
      instructions:
      - text: Replace order history {id} with the full record for ERP order {erpOrderNumber}.
        slots:
          id: path.id
          erpOrderNumber: requestBody.erpOrderNumber
      - text: Overwrite past order {id} entirely, with order total {orderTotal}.
        slots:
          id: path.id
          orderTotal: requestBody.orderTotal
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistories({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a historical order
      effect: destructive
      questions:
      - How do I remove one order from the order history?
      - Can I delete a past order only if nobody changed it since I read it?
      instructions:
      - text: Delete order history {id}.
        slots:
          id: path.id
      - text: Remove past order {id} if its ETag is still {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistories({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update fields on a historical order
      effect: write
      questions:
      - How do I change the status of a past order in order history?
      - Can I update just the notes on an order history record?
      instructions:
      - text: Set the status of order history {id} to {status}.
        slots:
          id: path.id
          status: requestBody.status
      - text: Update the notes on past order {id} to {notes}.
        slots:
          id: path.id
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistories/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank order history template
      effect: read
      questions:
      - What default values does a new order history record start with?
      - Can I fetch an empty order history template before loading orders?
      instructions:
      - text: Fetch the default order history template.
      - text: Show me the starting values for a new order history record.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/orderhistories/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete historical orders
      effect: destructive
      questions:
      - How do I delete several past orders at once?
      - Can I purge a batch of order history records by ID?
      instructions:
      - text: Bulk delete the order histories with IDs {ids}.
        slots:
          ids: query.ids
      - text: 'Remove these past orders in one call: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/orderhistories({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a historical order
      effect: read
      questions:
      - How do I read a custom property stored on a past order?
      - Can I fetch one extra field value from an order history record?
      instructions:
      - text: Get custom property {custompropertyKey} on order history {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show the custom property {custompropertyKey} of past order {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/orderhistories({key})/orderhistorylines({orderhistorylineKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a line item on a historical order
      effect: read
      questions:
      - How do I see a single product line from a past order?
      - Can I read one order history line by its key?
      instructions:
      - text: Get line {orderhistorylineKey} of order history {key}.
        slots:
          orderhistorylineKey: path.orderhistorylineKey
          key: path.key
      - text: Show product line {orderhistorylineKey} on past order {key}.
        slots:
          orderhistorylineKey: path.orderhistorylineKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/orderhistories({key})/orderhistorypromotions({orderhistorypromotionKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a promotion applied to a historical order
      effect: read
      questions:
      - Which promotion was applied to a past order?
      - Can I read one order history promotion record by its key?
      instructions:
      - text: Get promotion {orderhistorypromotionKey} on order history {key}.
        slots:
          orderhistorypromotionKey: path.orderhistorypromotionKey
          key: path.key
      - text: Show the promotion {orderhistorypromotionKey} applied to past order {key}.
        slots:
          orderhistorypromotionKey: path.orderhistorypromotionKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/orderhistories({key})/orderhistorytaxes({orderhistorytaxKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tax entry on a historical order
      effect: read
      questions:
      - How do I see the tax breakdown entry for a past order?
      - Can I read one order history tax record by its key?
      instructions:
      - text: Get tax entry {orderhistorytaxKey} on order history {key}.
        slots:
          orderhistorytaxKey: path.orderhistorytaxKey
          key: path.key
      - text: Show tax line {orderhistorytaxKey} for past order {key}.
        slots:
          orderhistorytaxKey: path.orderhistorytaxKey
          key: path.key
      method: generated
      generated: '2026-09-26'