# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Overview Tracking API
  version: 1.0.0
extends: openapi/aftership-tracking-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: 7
- target: $.paths['/trackings'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter shipment trackings
      effect: read
      questions:
      - How do I list all the shipments I'm tracking?
      - Can I find trackings by tracking number, courier or tag?
      - Which shipments were returned to sender?
      instructions:
      - text: List my trackings.
      - text: Find trackings for tracking numbers {tracking_numbers}.
        slots:
          tracking_numbers: query.tracking_numbers
      - text: Show trackings with tag {tag} shipped by {slug}.
        slots:
          tag: query.tag
          slug: query.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/trackings'].post
  update:
    x-apievangelist-phrasing:
      intent: Start tracking a shipment
      effect: write
      questions:
      - How do I start tracking a package with AfterShip?
      - Do I need to know the courier to add a tracking number?
      instructions:
      - text: Track {tracking_number}.
        slots:
          tracking_number: requestBody.tracking_number
      - text: Add tracking {tracking_number} with courier {slug} for order {order_number}.
        slots:
          tracking_number: requestBody.tracking_number
          slug: requestBody.slug
          order_number: requestBody.order_number
      method: generated
      generated: '2026-09-26'
- target: $.paths['/trackings/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a tracking's latest status
      effect: read
      questions:
      - Where is my package right now?
      - Can I get tracking checkpoints translated into another language?
      instructions:
      - text: Get tracking {id}.
        slots:
          id: path.id
      - text: Show the checkpoints for tracking {id} in language {lang}.
        slots:
          id: path.id
          lang: query.lang
      method: generated
      generated: '2026-09-26'
- target: $.paths['/trackings/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a tracking's details
      effect: write
      questions:
      - Can I change the courier or order number on an existing tracking?
      - How do I update the promised delivery date on a tracking?
      instructions:
      - text: Set the title of tracking {id} to {title}.
        slots:
          id: path.id
          title: requestBody.title
      - text: Change the courier of tracking {id} to {slug}.
        slots:
          id: path.id
          slug: requestBody.slug
      - text: Update tracking {id} promised delivery date to {order_promised_delivery_date}.
        slots:
          id: path.id
          order_promised_delivery_date: requestBody.order_promised_delivery_date
      method: generated
      generated: '2026-09-26'
- target: $.paths['/trackings/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a tracking
      effect: destructive
      questions:
      - How do I stop tracking and remove a shipment?
      - Can I delete a tracking I added by mistake?
      instructions:
      - text: Delete tracking {id}.
        slots:
          id: path.id
      - text: Remove the tracking {id} from my account.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/trackings/{id}/retrack'].post
  update:
    x-apievangelist-phrasing:
      intent: Retrack an expired tracking
      effect: write
      questions:
      - Can I resume tracking a shipment after it expired?
      - How many times can an expired tracking be retracked?
      instructions:
      - text: Retrack expired tracking {id}.
        slots:
          id: path.id
      - text: Restart updates on the expired tracking {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/trackings/{id}/mark-as-completed'].post
  update:
    x-apievangelist-phrasing:
      intent: Mark a tracking as completed
      effect: write
      questions:
      - How do I manually mark a shipment as delivered or lost?
      - Will a tracking keep updating after I mark it completed?
      instructions:
      - text: Mark tracking {id} completed because {reason}.
        slots:
          id: path.id
          reason: requestBody.reason
      - text: Complete tracking {id} with reason {reason} as of {event_datetime}.
        slots:
          id: path.id
          reason: requestBody.reason
          event_datetime: requestBody.event_datetime
      method: generated
      generated: '2026-09-26'