duffel_get_order

Instructions

Retrieve complete details for an existing flight order.

This tool fetches:
- Order status and booking reference
- Flight itinerary and schedule
- Passenger information
- Payment and pricing details
- Documents and tickets
- Change and cancellation options

Use this when:
- User needs to review their booking
- Checking order status
- Before making changes or cancellations
- Retrieving booking reference for airline website

Returns order details in specified format (JSON or Markdown).

Implementation Reference

• duffel_mcp/tools/flights.py:369-458 (handler)

  The handler function that implements the core logic of duffel_get_order: makes API call to retrieve order details and formats the output in JSON or Markdown.

  async def get_order(params: GetOrderInput) -> str:
      """
      Retrieve complete details for an existing flight order.
      
      This tool fetches:
      - Order status and booking reference
      - Flight itinerary and schedule
      - Passenger information
      - Payment and pricing details
      - Documents and tickets
      - Change and cancellation options
      
      Use this when:
      - User needs to review their booking
      - Checking order status
      - Before making changes or cancellations
      - Retrieving booking reference for airline website
      
      Returns order details in specified format (JSON or Markdown).
      """
      try:
          response = await make_api_request(
              method="GET",
              endpoint=f"/air/orders/{params.order_id}"
          )
          
          order = response["data"]
          
          if params.response_format == ResponseFormat.JSON:
              return truncate_text(format_json_response(order))
          
          else:  # Markdown format
              lines = [
                  "# Flight Order Details",
                  "",
                  f"**Order ID**: `{order['id']}`",
                  f"**Booking Reference**: {order.get('booking_reference', 'N/A')}",
                  f"**Status**: {order.get('status', 'N/A')}",
                  f"**Total**: {format_currency(order['total_amount'], order['total_currency'])}",
                  f"**Booked**: {order.get('created_at', 'N/A')}",
                  "",
                  "## Passengers"
              ]
              
              for i, pax in enumerate(order.get("passengers", []), 1):
                  lines.append(f"{i}. {pax.get('given_name')} {pax.get('family_name')}")
                  if pax.get('born_on'):
                      lines.append(f"   - DOB: {pax['born_on']}")
              
              lines.append("")
              lines.append("## Flight Itinerary")
              
              for i, slice_info in enumerate(order.get("slices", []), 1):
                  origin = slice_info["origin"]
                  destination = slice_info["destination"]
                  lines.append(f"\n### Slice {i}: {origin['city_name']} → {destination['city_name']}")
                  lines.append(f"**Departure**: {slice_info['departure_at']} ({origin['iata_code']})")
                  lines.append(f"**Arrival**: {slice_info['arrival_at']} ({destination['iata_code']})")
                  lines.append(f"**Duration**: {format_duration(slice_info.get('duration', ''))}")
                  
                  for j, segment in enumerate(slice_info.get("segments", []), 1):
                      carrier = segment.get("marketing_carrier", {})
                      lines.append(f"\n**Flight {j}**: {carrier.get('name', 'N/A')} {segment.get('marketing_carrier_flight_number', '')}")
                      lines.append(f"- Aircraft: {segment.get('aircraft', {}).get('name', 'N/A')}")
              
              conditions = order.get("conditions", {})
              if conditions:
                  lines.append("\n## Booking Conditions")
                  
                  change_before = conditions.get("change_before_departure", {})
                  if change_before:
                      allowed = "✅ Yes" if change_before.get("allowed") else "❌ No"
                      lines.append(f"- Changes before departure: {allowed}")
                      if change_before.get("penalty_amount"):
                          penalty = format_currency(
                              change_before["penalty_amount"],
                              change_before.get("penalty_currency", "")
                          )
                          lines.append(f"  - Change fee: {penalty}")
                  
                  refund_before = conditions.get("refund_before_departure", {})
                  if refund_before:
                      allowed = "✅ Yes" if refund_before.get("allowed") else "❌ No"
                      lines.append(f"- Refund before departure: {allowed}")
              
              return truncate_text("\n".join(lines))
              
      except Exception as e:
          return f"Error retrieving order: {str(e)}\n\nTroubleshooting:\n- Verify the order ID is correct (starts with 'ord_')\n- Check if you have access to this order\n- Order might not exist or might have been cancelled"

• duffel_mcp/models/flights.py:221-234 (schema)

  Pydantic model defining the input schema for the tool: requires order_id matching 'ord_*' pattern and optional response_format.

  class GetOrderInput(BaseModel):
      """Input for retrieving order details."""
      model_config = ConfigDict(str_strip_whitespace=True, validate_assignment=True, extra='forbid')
  
      order_id: str = Field(
          ...,
          description="Duffel order ID (e.g., 'ord_00009hthhsUZ8W4LxQgkjo')",
          pattern="^ord_[a-zA-Z0-9]+$"
      )
      response_format: ResponseFormat = Field(
          default=ResponseFormat.MARKDOWN,
          description="Output format: 'json' for raw data or 'markdown' for readable summary"
      )

• duffel_mcp/tools/flights.py:359-368 (registration)

  MCP tool registration decorator that registers the get_order function as the 'duffel_get_order' tool with appropriate annotations.

  @mcp.tool(
      name="duffel_get_order",
      annotations={
          "title": "Get Order Details",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True
      }
  )