# 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 History Promotions API
  version: 1.0.0
extends: openapi/optimizely-order-history-promotions-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: 9
- target: $.paths['/api/v1/admin/OrderHistoryPromotions'].get
  update:
    x-apievangelist-phrasing:
      intent: List promotions recorded on past orders
      effect: read
      questions:
      - Which promotions were applied to historical orders?
      - Can I filter order history promotions by promotion?
      instructions:
      - text: List all order history promotions.
      - text: Show order history promotions matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistoryPromotions'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a promotion on a historical order
      effect: write
      questions:
      - How do I record a discount against an order from order history?
      - Can I attach a promotion to a specific line of a past order?
      instructions:
      - text: Record promotion {promotionId} worth {amount} on order history {orderHistoryId}.
        slots:
          promotionId: requestBody.promotionId
          amount: requestBody.amount
          orderHistoryId: requestBody.orderHistoryId
      - text: Add promotion {name} to order history line {orderHistoryLineId}.
        slots:
          name: requestBody.name
          orderHistoryLineId: requestBody.orderHistoryLineId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistoryPromotions({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a promotion on a past order
      effect: read
      questions:
      - How much did a promotion save on a historical order?
      - Can I look up one order history promotion by ID?
      instructions:
      - text: Get order history promotion {id}.
        slots:
          id: path.id
      - text: Show the discount amount of order history promotion {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistoryPromotions({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a promotion on a past order
      effect: write
      questions:
      - How do I overwrite every field of an order history promotion?
      - Can I fully replace a promotion recorded on a past order?
      instructions:
      - text: Replace order history promotion {id} with promotion {promotionId} and amount {amount}.
        slots:
          id: path.id
          promotionId: requestBody.promotionId
          amount: requestBody.amount
      - text: Overwrite all fields of order history promotion {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistoryPromotions({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a promotion from a past order
      effect: destructive
      questions:
      - How do I remove a promotion record from order history?
      - Does deleting an order history promotion use If-Match?
      instructions:
      - text: Delete order history promotion {id}.
        slots:
          id: path.id
      - text: Remove order history promotion {id} if its ETag is {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistoryPromotions({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Correct the amount on a past order promotion
      effect: write
      questions:
      - How do I fix the discount amount recorded on an old order?
      - Can I rename a promotion on a historical order without replacing it?
      instructions:
      - text: Change the amount on order history promotion {id} to {amount}.
        slots:
          id: path.id
          amount: requestBody.amount
      - text: Rename existing order history promotion {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/OrderHistoryPromotions/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get defaults for a new order history promotion
      effect: read
      questions:
      - What defaults does a new order history promotion start with?
      - Is there a blank order history promotion template?
      instructions:
      - text: Get the default field values for a new order history promotion.
      - text: Show a blank order history promotion record.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/orderhistorypromotions/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several order history promotions
      effect: destructive
      questions:
      - How do I bulk delete promotions from order history?
      - Can I remove many order history promotions in one request?
      instructions:
      - text: Bulk delete order history promotions {ids}.
        slots:
          ids: query.ids
      - text: Permanently delete every order history promotion in {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/orderhistorypromotions({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on an order history promotion
      effect: read
      questions:
      - How do I read a custom property on an order history promotion?
      - Can I fetch one custom field value from a past order's promotion?
      instructions:
      - text: Get custom property {custompropertyKey} of order history promotion {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Show the {custompropertyKey} custom property on order history promotion {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'