MAQAMI Travel

Get flight cancellation status

get_flights_bookings_bookingid_cancellations

Read-onlyIdempotent

Preview flight booking cancellation refund eligibility, estimated refund and penalty amounts without cancelling. Use bookingId and booking email to see financial impact.

Instructions

Overview

Returns refund eligibility, estimated refund amounts, and penalty details for a booking without actually cancelling it. Useful before post_flights_bookings_bookingid_cancellations to understand the financial impact of cancellation.

When to Use

Pre-cancellation review — Show the customer the potential maximum refund (not guaranteed) before they confirm cancellation
Refund estimation — Display potential maximum refund and penalty amounts in the booking management UI (refund is not granted until cancel completes)
Eligibility check — Determine whether the booking is within the void window (isVoidable) or eligible for a partial refund (isRefundable)

What You Get

confidence — How reliable the quote is (confirmed, estimated, heuristic, unknown)
isRefundable / isVoidable — Quick eligibility flags
refund / penalty — Aggregate amounts with margin applied. refund is the potential maximum the airline may refund — not a granted/guaranteed amount
penalties[] — Itemised penalty breakdown when available
tickets[] — Per-ticket detail when available
destination — Where the refund goes
vouchers[] — Airline travel vouchers / credit-shells when destination is voucher; omitted when absent. Distinct from MAQAMI discount voucherCode on prebook

Concurrent cancellation

If a cancellation was already submitted and is still awaiting provider confirmation, this endpoint returns HTTP 409 with code 49007 (CONCURRENT_OPERATION). A new quote is not available until that cancellation completes or fails.

Refund amount caveat

The refund amount on a cancellation quote is the potential maximum the airline may refund if cancellation proceeds under the quoted conditions. It is an estimate for decision-making only and is not granted — the final refund (if any) is determined when cancellation completes and may be lower or zero. The refund may arrive asynchronously once the airline determines the final amount.

Key Features

Non-destructive — Does not cancel the booking; safe to call before user confirmation
Margin-applied pricing — All amounts (including voucher pricing.display) reflect the same margin applied at booking time

Quick Start

Provide the bookingId from the flight booking confirmation. Each call checks the airline live.

Requires the bookingId and the email used to book: the server only returns or changes a booking when they match.

Input Schema

Name	Required	Description
`email`	Yes	The email address used to make the booking. The server checks it against the booking before returning or changing anything.
`lastName`	No	The booking holder's last name, if the customer gives it. Optional.
`bookingId`	Yes	The unique booking identifier

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv1.0.6Oct 7, 2026

addedInput schema / properties / email

Added value: +{
+  "description": "The email address used to make the booking. The server checks it against the booking before returning or changing anything.",
+  "type": "string"
+}

addedInput schema / properties / lastName

Added value: +{
+  "description": "The booking holder's last name, if the customer gives it. Optional.",
+  "type": "string"
+}

changedInput schema / required

Previous value: -[
-  "bookingId"
-]New value: +[
+  "bookingId",
+  "email"
+]

First observedv0.1.0Sep 28, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, and non-destructive, but the description adds substantial behavioral context beyond them: HTTP 409 with code 49007 when a concurrent cancellation is pending, the caveat that refunds are potential maximums not granted amounts, async refund arrival, margin-applied pricing, and the email-match auth requirement. This is unusually rich disclosure for a read tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with an Overview and well-organized headers, so the key facts come first. It is somewhat long and repeats the refund-maximum caveat in both 'What You Get' and a dedicated 'Refund amount caveat' section, which costs a point on conciseness despite the clean structure.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must describe return values, and the 'What You Get' section enumerates the response fields (confidence, isRefundable/isVoidable, refund/penalty, penalties[], tickets[], destination, vouchers[]) in detail. Combined with the 409/async/margin behavior, an agent has everything needed to call and interpret the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so bookingId, email, and lastName are already documented per-field, including the email-verification check. The description's 'Requires the bookingId and the email used to book' largely restates that, adding no new syntax or format detail. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The Overview states a specific verb and resource: returns refund eligibility, estimated refund amounts, and penalty details for a flight booking. It explicitly distinguishes itself from the sibling post_flights_bookings_bookingid_cancellations by stating it works 'without actually cancelling it', so an agent can route correctly without opening either schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

A dedicated 'When to Use' section names three concrete scenarios (pre-cancellation review, refund estimation, eligibility check) and positions the tool as a precursor to the cancellation sibling. The 'Concurrent cancellation' section also states the condition (already-submitted cancellation) under which the tool fails, which is explicit when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server