# 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 Vias API
  version: 1.0.0
extends: openapi/optimizely-ship-vias-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: 15
- target: $.paths['/api/v1/admin/ShipVias'].get
  update:
    x-apievangelist-phrasing:
      intent: List shipping methods
      effect: read
      questions:
      - Which ship vias (shipping methods) are configured in my commerce store?
      - Can I filter shipping methods to only the pickup options?
      - How many ship via records does the commerce admin have?
      instructions:
      - text: List all ship vias.
      - text: List ship vias matching the filter {filter}.
        slots:
          filter: query.$filter
      - text: Show the first {top} shipping methods ordered by {orderby}.
        slots:
          top: query.$top
          orderby: query.$orderby
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipVias'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a shipping method
      effect: write
      questions:
      - How do I add a new shipping method with its ERP ship code?
      - Can I give a new ship via a flat fee and a minimum fee?
      instructions:
      - text: Create ship via {description} with ship code {shipCode} and ERP code {erpShipCode}.
        slots:
          description: requestBody.description
          shipCode: requestBody.shipCode
          erpShipCode: requestBody.erpShipCode
      - text: Add a shipping method {shipCode} for carrier {carrierId} with a flat fee of {flatFee}.
        slots:
          shipCode: requestBody.shipCode
          carrierId: requestBody.carrierId
          flatFee: requestBody.flatFee
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipVias({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shipping method
      effect: read
      questions:
      - What fees and carrier does one ship via use?
      - Can I look up a single shipping method by its ID?
      instructions:
      - text: Get ship via {id}.
        slots:
          id: path.id
      - text: Show the settings of shipping method {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipVias({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a shipping method
      effect: write
      questions:
      - How do I overwrite a ship via with a completely new definition?
      - Does replacing a shipping method clear the fields I don't send?
      instructions:
      - text: Replace ship via {id} with ship code {shipCode}, ERP code {erpShipCode} and description {description}.
        slots:
          id: path.id
          shipCode: requestBody.shipCode
          erpShipCode: requestBody.erpShipCode
          description: requestBody.description
      - text: Overwrite all fields of shipping method {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipVias({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a shipping method
      effect: destructive
      questions:
      - Can I permanently delete one ship via by its ID?
      - Is it possible to delete a shipping method only when its ETag matches?
      instructions:
      - text: Delete ship via {id}.
        slots:
          id: path.id
      - text: Delete shipping method {id} if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipVias({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a shipping method
      effect: write
      questions:
      - How do I disable a single shipping method without resending all of it?
      - Can I make an existing ship via the default option?
      instructions:
      - text: Set enable to {enable} on ship via {id}.
        slots:
          id: path.id
          enable: requestBody.enable
      - text: Change the minimum fee of shipping method {id} to {minimumFee}.
        slots:
          id: path.id
          minimumFee: requestBody.minimumFee
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipVias/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a blank shipping method template
      effect: read
      questions:
      - What default values does a new ship via start with?
      - Can I fetch an empty shipping method template?
      instructions:
      - text: Fetch the default ship via template.
      - text: Show me the default values for a new shipping method.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/ShipVias/Default.archive'].post
  update:
    x-apievangelist-phrasing:
      intent: Archive shipping methods
      effect: destructive
      questions:
      - Can I archive shipping methods instead of deleting them?
      - How do I retire several ship vias with the archive action?
      instructions:
      - text: Archive the ship vias {ids} using the Default.archive action.
        slots:
          ids: query.ids
      - text: Run the archive operation on shipping methods {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipvias/archive'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive shipping methods via the route
      effect: destructive
      questions:
      - Is there a DELETE route that archives ship vias rather than removing them?
      - What does the shipvias/archive route do with the IDs I pass?
      instructions:
      - text: Archive ship vias {ids} through the shipvias/archive route.
        slots:
          ids: query.ids
      - text: Use the archive route to retire shipping methods {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipvias/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete shipping methods
      effect: destructive
      questions:
      - Can I permanently delete several ship vias at once?
      - How do I remove a batch of shipping methods by ID?
      instructions:
      - text: Bulk delete the ship vias {ids}.
        slots:
          ids: query.ids
      - text: 'Permanently remove these shipping methods: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipvias({key})/customerorders({customerorderKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an order shipped with a ship via
      effect: read
      questions:
      - Was a specific customer order shipped with a given shipping method?
      - Can I look up one customer order under a ship via?
      instructions:
      - text: Get customer order {customerorderKey} under ship via {key}.
        slots:
          customerorderKey: path.customerorderKey
          key: path.key
      - text: Show order {customerorderKey} that used shipping method {key}.
        slots:
          customerorderKey: path.customerorderKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipvias({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a ship via
      effect: read
      questions:
      - Can I read a custom property stored on a shipping method?
      - What extra custom field values does a ship via carry?
      instructions:
      - text: Get custom property {custompropertyKey} on ship via {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show shipping method {key}'s custom property {custompropertyKey}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipvias({key})/shipcharges({shipchargeKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a ship charge for a ship via
      effect: read
      questions:
      - What ship charge is defined for a particular shipping method?
      - Can I look up one shipping charge row under a ship via?
      instructions:
      - text: Get ship charge {shipchargeKey} on ship via {key}.
        slots:
          shipchargeKey: path.shipchargeKey
          key: path.key
      - text: Show the charge {shipchargeKey} configured for shipping method {key}.
        slots:
          shipchargeKey: path.shipchargeKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipvias({key})/shiprates({shiprateKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a ship rate for a ship via
      effect: read
      questions:
      - Which rate tier applies to a given shipping method?
      - Can I fetch a single ship rate belonging to a ship via?
      instructions:
      - text: Get ship rate {shiprateKey} on ship via {key}.
        slots:
          shiprateKey: path.shiprateKey
          key: path.key
      - text: Show rate {shiprateKey} for shipping method {key}.
        slots:
          shiprateKey: path.shiprateKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipvias({key})/shiprules({shipruleKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a ship rule for a ship via
      effect: read
      questions:
      - What shipping rule restricts when a ship via can be used?
      - Can I look up one ship rule attached to a shipping method?
      instructions:
      - text: Get ship rule {shipruleKey} on ship via {key}.
        slots:
          shipruleKey: path.shipruleKey
          key: path.key
      - text: Show rule {shipruleKey} applied to shipping method {key}.
        slots:
          shipruleKey: path.shipruleKey
          key: path.key
      method: generated
      generated: '2026-09-26'