# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Overview Fulfillments API
  version: 1.0.0
extends: openapi/aftership-fulfillments-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: 5
- target: $.paths['/fulfillments'].get
  update:
    x-apievangelist-phrasing:
      intent: List fulfillments for an order
      effect: read
      questions:
      - How do I see all fulfillments for an order?
      - Can I fetch several fulfillments at once by their IDs?
      instructions:
      - text: List fulfillments for order {order_id} in store {store}.
        slots:
          order_id: query.order_id
          store: header.as-store-id
      - text: Get fulfillments {ids} from store {store}.
        slots:
          ids: query.ids[]
          store: header.as-store-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/fulfillments'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a fulfillment for an order
      effect: write
      questions:
      - How do I record that part of an order has shipped?
      - Can I create a buy-online-pick-up-in-store fulfillment?
      instructions:
      - text: Create a fulfillment for order {order_id} with line items {line_items} via {delivery_method}.
        slots:
          order_id: requestBody.order_id
          line_items: requestBody.line_items
          delivery_method: requestBody.delivery_method
      - text: Add a {status} fulfillment to order {order_id} in store {store}.
        slots:
          status: requestBody.status
          order_id: requestBody.order_id
          store: header.as-store-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/fulfillments/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a fulfillment by ID
      effect: read
      questions:
      - What are the details of one specific fulfillment?
      - Can I look up a fulfillment by its ID?
      instructions:
      - text: Show fulfillment {id} in store {store}.
        slots:
          id: path.id
          store: header.as-store-id
      - text: Get fulfillment {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/fulfillments/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a fulfillment's tracking or pickup info
      effect: write
      questions:
      - How do I add tracking numbers to an existing fulfillment?
      - Can I change the pickup location on a fulfillment?
      instructions:
      - text: Add trackings {trackings} to fulfillment {id}.
        slots:
          trackings: requestBody.trackings
          id: path.id
      - text: Change the pickup location of fulfillment {id} to {pickup_location}.
        slots:
          id: path.id
          pickup_location: requestBody.pickup_location
      method: generated
      generated: '2026-09-26'
- target: $.paths['/fulfillments/{id}/update-status'].post
  update:
    x-apievangelist-phrasing:
      intent: Move a fulfillment to its next status
      effect: write
      questions:
      - What order do fulfillment statuses have to be updated in?
      - How do I mark a fulfillment as ready for pickup or picked up?
      instructions:
      - text: Set fulfillment {id} status to {status} as of {occurred_at}.
        slots:
          id: path.id
          status: requestBody.status
          occurred_at: requestBody.occurred_at
      - text: Advance fulfillment {id} in store {store} to {status}.
        slots:
          id: path.id
          store: header.as-store-id
          status: requestBody.status
      method: generated
      generated: '2026-09-26'