API Evangelist conversational phrasing for Admin API V1 Shipments API

# 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 Shipments API
  version: 1.0.0
extends: openapi/optimizely-shipments-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: 10
- target: $.paths['/api/v1/admin/Shipments'].get
  update:
    x-apievangelist-phrasing:
      intent: List order shipments
      effect: read
      questions:
      - Which shipments have gone out for my commerce orders?
      - Can I filter shipments by web order number or shipment date?
      instructions:
      - text: List all shipments.
      - text: Find shipments matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Shipments'].post
  update:
    x-apievangelist-phrasing:
      intent: Record a shipment for an order
      effect: write
      questions:
      - How do I record a new shipment against an order?
      - What is required to create a shipment, web and ERP order numbers?
      instructions:
      - text: Create shipment {shipmentNumber} for web order {webOrderNumber} and ERP order {erpOrderNumber}.
        slots:
          shipmentNumber: requestBody.shipmentNumber
          webOrderNumber: requestBody.webOrderNumber
          erpOrderNumber: requestBody.erpOrderNumber
      - text: Record shipment {shipmentNumber} shipped on {shipmentDate} for ERP order {erpOrderNumber}.
        slots:
          shipmentNumber: requestBody.shipmentNumber
          shipmentDate: requestBody.shipmentDate
          erpOrderNumber: requestBody.erpOrderNumber
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Shipments({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shipment by ID
      effect: read
      questions:
      - When did a specific shipment go out and was the ASN sent?
      - Can I look up one shipment record by its ID?
      instructions:
      - text: Get shipment {id}.
        slots:
          id: path.id
      - text: Show the shipment and ASN dates for shipment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Shipments({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a shipment record
      effect: write
      questions:
      - Can I overwrite an entire shipment record in one request?
      - Does fully replacing a shipment require the order numbers again?
      instructions:
      - text: Replace shipment {id} with shipment number {shipmentNumber}, web order {webOrderNumber}, ERP order {erpOrderNumber}.
        slots:
          id: path.id
          shipmentNumber: requestBody.shipmentNumber
          webOrderNumber: requestBody.webOrderNumber
          erpOrderNumber: requestBody.erpOrderNumber
      - text: Overwrite the whole shipment record {id} using a full PUT.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Shipments({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a shipment by ID
      effect: destructive
      questions:
      - How do I delete a shipment record entered in error?
      - Does deleting a shipment accept an If-Match ETag?
      instructions:
      - text: Delete shipment {id}.
        slots:
          id: path.id
      - text: Delete shipment {id} only if its ETag matches {ifMatch}.
        slots:
          id: path.id
          ifMatch: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Shipments({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a shipment
      effect: write
      questions:
      - How do I mark the shipment email or ASN as sent on an existing shipment?
      - Can I correct just the shipment date on a shipment?
      instructions:
      - text: Set the ASN sent date on shipment {id} to {asnSentDate}.
        slots:
          id: path.id
          asnSentDate: requestBody.asnSentDate
      - text: Update the shipment date of shipment {id} to {shipmentDate}.
        slots:
          id: path.id
          shipmentDate: requestBody.shipmentDate
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Shipments/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a default shipment template
      effect: read
      questions:
      - What default values does a new shipment start with?
      - Is there a blank shipment template to fetch before creating one?
      instructions:
      - text: Fetch the default shipment template.
      - text: Show me the default values for a new shipment.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipments/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete shipments
      effect: destructive
      questions:
      - How do I delete several shipment records at once?
      - Can I pass a list of IDs to remove many shipments?
      instructions:
      - text: Bulk delete the shipments with IDs {ids}.
        slots:
          ids: query.ids
      - text: 'Remove all of these shipment records in one call: {ids}.'
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipments({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a shipment
      effect: read
      questions:
      - Where do I read a custom property stored on a shipment?
      - Can I fetch one extra property value from a shipment record?
      instructions:
      - text: Get custom property {custompropertyKey} on shipment {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show the custom property {custompropertyKey} of shipment {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/shipments({key})/shipmentpackages({shipmentpackageKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a package within a shipment
      effect: read
      questions:
      - What tracking details does one package in a shipment have?
      - Can I fetch a single package that belongs to a shipment?
      instructions:
      - text: Get package {shipmentpackageKey} of shipment {key}.
        slots:
          shipmentpackageKey: path.shipmentpackageKey
          key: path.key
      - text: Show shipment package {shipmentpackageKey} inside shipment {key}.
        slots:
          shipmentpackageKey: path.shipmentpackageKey
          key: path.key
      method: generated
      generated: '2026-09-26'