# 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 Ship Rates API
  version: 1.0.0
extends: openapi/optimizely-ship-rates-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/ShipRates'].get
  update:
    x-apievangelist-phrasing:
      intent: List shipping rates
      effect: read
      questions:
      - What shipping charges are set up by order amount?
      - Can I filter ship rates to a single ship via?
      instructions:
      - text: List all ship rates.
      - text: List ship rates matching {filter}, ordered by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRates'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a shipping rate
      effect: write
      questions:
      - How do I charge a flat shipping fee above a certain order amount?
      - Can a new ship rate charge per item instead of per order?
      instructions:
      - text: Create a ship rate for ship via {shipViaId} charging {chargeAmount} on orders of {orderAmount}.
        slots:
          shipViaId: requestBody.shipViaId
          chargeAmount: requestBody.chargeAmount
          orderAmount: requestBody.orderAmount
      - text: Add a per-each ship rate of {chargeAmount} for ship via {shipViaId}, per each set to {perEach}.
        slots:
          chargeAmount: requestBody.chargeAmount
          shipViaId: requestBody.shipViaId
          perEach: requestBody.perEach
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRates({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shipping rate
      effect: read
      questions:
      - Can I look up one ship rate by its ID?
      - What charge amount does a particular ship rate apply?
      instructions:
      - text: Show ship rate {id}.
        slots:
          id: path.id
      - text: Get ship rate {id} returning only {select}.
        slots:
          id: path.id
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRates({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a shipping rate
      effect: write
      questions:
      - Can I overwrite a ship rate record completely?
      - What's the full-replace call for a shipping rate?
      instructions:
      - text: Replace ship rate {id} with charge {chargeAmount} at order amount {orderAmount}.
        slots:
          id: path.id
          chargeAmount: requestBody.chargeAmount
          orderAmount: requestBody.orderAmount
      - text: Overwrite ship rate {id} for ship via {shipViaId}.
        slots:
          id: path.id
          shipViaId: requestBody.shipViaId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRates({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a shipping rate
      effect: destructive
      questions:
      - How do I remove one shipping rate tier?
      - Can I delete a ship rate conditionally on its ETag?
      instructions:
      - text: Delete ship rate {id}.
        slots:
          id: path.id
      - text: Delete ship rate {id} if its ETag matches {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRates({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a shipping rate's charge
      effect: write
      questions:
      - Can I change only the charge amount of a ship rate?
      - Is there a partial update for the order threshold of a rate?
      instructions:
      - text: Set ship rate {id} charge to {chargeAmount}.
        slots:
          id: path.id
          chargeAmount: requestBody.chargeAmount
      - text: Patch ship rate {id} order amount to {orderAmount}.
        slots:
          id: path.id
          orderAmount: requestBody.orderAmount
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipRates/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a shipping rate
      effect: read
      questions:
      - What defaults are pre-filled for a new ship rate?
      - Is there a blank ship rate template?
      instructions:
      - text: Get the default ship rate template.
      - text: Show pre-filled values for a new shipping rate.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shiprates/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several shipping rates
      effect: destructive
      questions:
      - Can I bulk delete ship rates in one request?
      - Which call removes many shipping rates by ID?
      instructions:
      - text: Bulk delete ship rates {ids}.
        slots:
          ids: query.ids
      - text: Remove the shipping rates {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shiprates({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a shipping rate
      effect: read
      questions:
      - Can I read a custom field stored on a ship rate?
      - Where are extra attributes of a shipping rate kept?
      instructions:
      - text: Get custom property {custompropertyKey} on ship rate {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show ship rate {key}'s custom field {custompropertyKey}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'