# 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 Customer Order Taxes API
  version: 1.0.0
extends: openapi/optimizely-customer-order-taxes-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/CustomerOrderTaxes'].get
  update:
    x-apievangelist-phrasing:
      intent: List tax lines on customer orders
      effect: read
      questions:
      - What tax lines have been applied to orders in Optimizely Commerce?
      - Can I filter order tax lines to a single customer order?
      instructions:
      - text: List all customer order tax lines.
      - text: Show order tax lines matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrderTaxes'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a tax line to a customer order
      effect: write
      questions:
      - How do I attach a tax line with a code and rate to an order?
      - Can I set the tax amount directly when adding an order tax?
      instructions:
      - text: Add tax {taxCode} ({taxDescription}) at rate {taxRate} to order {customerOrderId}.
        slots:
          taxCode: requestBody.taxCode
          taxDescription: requestBody.taxDescription
          taxRate: requestBody.taxRate
          customerOrderId: requestBody.customerOrderId
      - text: Create order tax {taxCode} described as {taxDescription} for {taxAmount}.
        slots:
          taxCode: requestBody.taxCode
          taxDescription: requestBody.taxDescription
          taxAmount: requestBody.taxAmount
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrderTaxes({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one order tax line
      effect: read
      questions:
      - What rate and amount were charged on a specific order tax line?
      - Can I look up a single order tax record by id?
      instructions:
      - text: Fetch order tax line {id}.
        slots:
          id: path.id
      - text: Show the code, rate and amount of order tax {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrderTaxes({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace an order tax line
      effect: write
      questions:
      - Can I overwrite an order tax line in full?
      - Does replacing an order tax require resending its code and description?
      instructions:
      - text: Replace order tax {id} with code {taxCode} and description {taxDescription}.
        slots:
          id: path.id
          taxCode: requestBody.taxCode
          taxDescription: requestBody.taxDescription
      - text: Overwrite the full record of order tax line {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrderTaxes({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one order tax line
      effect: destructive
      questions:
      - How do I remove a tax line from an order?
      - Can deleting an order tax be conditional on its ETag?
      instructions:
      - text: Delete order tax line {id}.
        slots:
          id: path.id
      - text: Delete order tax {id} only if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrderTaxes({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Adjust the rate or amount of an order tax
      effect: write
      questions:
      - Can I correct just the tax amount on an order tax line?
      - Is it possible to change the display order of tax lines on an order?
      instructions:
      - text: Set the tax amount of order tax {id} to {taxAmount}.
        slots:
          id: path.id
          taxAmount: requestBody.taxAmount
      - text: Change order tax {id} to rate {taxRate} and sort position {sortOrder}.
        slots:
          id: path.id
          taxRate: requestBody.taxRate
          sortOrder: requestBody.sortOrder
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/CustomerOrderTaxes/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for an order tax line
      effect: read
      questions:
      - What defaults does a new order tax line start with?
      - Is there a blank order tax template?
      instructions:
      - text: Get the default field values for a new order tax line.
      - text: Show the empty customer order tax template.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerordertaxes/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete order tax lines
      effect: destructive
      questions:
      - Can I remove many order tax lines in one request?
      - Is there a batch delete for order taxes by id list?
      instructions:
      - text: Bulk delete order tax lines {ids}.
        slots:
          ids: query.ids
      - text: Permanently delete every order tax in {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/customerordertaxes({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on an order tax line
      effect: read
      questions:
      - How can I read a custom property stored on an order tax line?
      - Can I fetch one custom field value from an order tax record?
      instructions:
      - text: Get custom property {custompropertyKey} of order tax {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      - text: Show the {custompropertyKey} custom property on order tax line {key}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'