Flight Refund

Tool description (what the LLM sees)

Cancels a booked flight, refunding tickets or voiding them inside the airline's void window.

get_booking with booking_ref (and last_name for guests) returns items[] with servicing eligibility and refusal reasons for item selection. The same booking_ref + booked_item_id identifies the selected item on every action, including commit and status. booked_item_id is the stable booked item, even after an exchange. last_name is required for guests and optional for authenticated owners. A 409 with items[] means customer selection is needed; a retry identifies that choice with booked_item_id.

The preview costs nothing and cancels nothing. The workflow is preview → commit → status:
1. action="preview" (the default) with booking_ref + booked_item_id (plus last_name for guests) returns refund versus void, the penalty, the customer refund, covered tickets, and an "svq_…" quote handle.
2. The preview's penalty and customer refund are the figures the customer agrees to.
3. action="commit" takes the same identity as the preview, quote_id="svq_…", and acknowledged = the preview's refund object (value, currency, decimal_places), copied field for field. It returns an "svc_…" operation handle. The platform refuses a commit without a live quote handle from a preview. When the amount has moved since the preview, it refuses the commit and returns a fresh quote with the new figure.
4. action="status" with the same booking_ref + booked_item_id and operation="svc_…" reports the airline's answer, every ticket's state, and the money's progress through its terminal state.

A void returns the original charge except any part the preview lists as paid later; a refund returns what the customer paid less the penalty. The preview identifies which outcome applies, lists covered documents and marks extras excluded from its immediate refund. Its customer refund and penalty are the customer-facing figures.

fee_known: false means the penalty and amount remain to be confirmed, rather than free cancellation. support_level "MANUAL_REQUIRED" means a person at Jinko completes the cancellation. A commit with manual_ok=true hands the cancellation to Jinko support; nothing reaches the airline until a person at Jinko completes it. Such a commit includes acknowledged when the preview carries a refund. When the penalty could not be established and the preview carries no refund, manual_ok travels without acknowledged and Jinko support establishes the amount.

action="check" (deprecated: use "preview") is a read-only eligibility probe that quotes no customer figure and returns no quote handle, so a commit cannot be made from it. A "Reason:" line on a check or refusal is the supplier's classification (NON_REFUNDABLE_FARE, EXCHANGED_TICKET, CARRIER_NOT_AUTHORIZED, DOCUMENT_RETIRED). These distinguish a fare nobody can refund from a ticket requiring an agent's manual refund; they are separate outcomes rather than a single "not refundable" answer.

Guest usage (no login required):
  flight_refund({ action: "preview", booking_ref: "JNK-A7B3X9", booked_item_id: "itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a", last_name: "Doe" })
Authenticated owner usage:
  flight_refund({ action: "preview", booking_ref: "JNK-A7B3X9", booked_item_id: "itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a" })

action="refund" (deprecated: use "preview" then "commit") is the legacy one-shot path for existing integrations: it prices and refunds in a single call, so no quote is shown before the refund.

A paid seat the airline settles itself is refunded once the airline refunds us; the preview lists it under seat_refunds as pending, separate from the fare refund.

Parameters

Name	Type	Required	Description
`action`	`enum ("preview" \| "commit" \| "status" \| "check" \| "refund")`	No	Action. “preview” (default) prices the cancellation and returns a quote handle without cancelling anything, it shows the customer whether this is a refund or a void, the penalty and the amount they get back. “commit” cancels, using the quote handle and the refund the customer acknowledged. “status” reports where a committed cancellation, its tickets and its refund got to. “check” (deprecated: use “preview”) is the read-only eligibility probe and quotes no customer figure. “refund” (deprecated: use “preview” then “commit”) is the legacy one-shot path that prices and refunds in a single call, with no chance to confirm the figures first.
`booking_ref`	`string`	Yes	Trip-level Jinko booking_ref returned by get_trip or submit_agent_payment. Use it to look up the booking with get_booking.
`booked_item_id`	`string \| null`	No	The booked item to service: booked_item_id from get_booking.items[] (an “itm_…” string). Send it on every action. May be omitted only when the booking has exactly one item in this domain.
`last_name`	`string \| null`	No	Primary traveler last name. Required for guests; optional for an authenticated owner of the booking.
`quote_id`	`string \| null`	No	The “svq_…” handle a prior action “preview” returned. Required for action “commit”. It binds the cancellation to the figures the customer was shown.
`acknowledged`	`object \| null`	No	The preview’s `refund` object copied field for field, the amount the customer agreed to. Required for action “commit”, except when submitting a MANUAL_REQUIRED preview that carried no figure at all (manual_ok, see below). It retains the original value and scale: the platform compares it against the live figure and refuses the commit with a fresh quote when they differ, rather than settling at a number nobody was shown.
`manual_ok`	`boolean`	No	For a preview with support_level “MANUAL_REQUIRED”, this flag hands it to Jinko support. Nothing is sent to the airline until a person at Jinko completes it. Without this flag such a commit is refused. The preview’s `refund` accompanies it as `acknowledged` whenever the preview carried one; a preview whose penalty was not established carries none, and then this flag travels alone and Jinko support establishes the amount.
`operation`	`string \| null`	No	The “svc_…” operation handle a prior action “commit” returned. Required for action “status”, unless you are following a legacy refund through refund_reference.
`user_intent`	`string`	No	The end user’s current request in their own words, e.g. “help me with my travel plans”. Pass it as-is when short; otherwise condense the goal and constraints into 1-2 sentences. Strip personal identifiers (names, emails, phone numbers, addresses, payment details), replace them with placeholders like “[name]”. Optional. Jinko uses it to understand demand, and hotel_search uses it to rank hotel results against what the user asked for (e.g. “quiet, with a gym, near Times Square”), so keep the user’s stated preferences in it.

Examples

Start with get_booking, then choose the flight’s booked_item_id. Use the same booking reference, item, and authentication throughout the operation. Preview the customer’s refund:

{
  "name": "flight_refund",
  "arguments": {
    "action": "preview",
    "booking_ref": "JNK-ABC123",
    "booked_item_id": "itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a",
    "last_name": "Doe"
  }
}

This example uses guest verification (booking_ref + last_name). An authenticated owner can omit last_name; the credential must own the booking. Choose one authentication mode and keep it for every action. Do not add order_id to these requests. Commit after the customer agrees to the preview: Copy the returned quote_id and the preview’s refund object into acknowledged, field for field. The values below are illustrative; use the actual preview values.

{
  "name": "flight_refund",
  "arguments": {
    "action": "commit",
    "booking_ref": "JNK-ABC123",
    "booked_item_id": "itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a",
    "last_name": "Doe",
    "quote_id": "svq_01J7ZQ8F4M3K9W2B",
    "acknowledged": { "value": 15977, "currency": "USD", "decimal_places": 2 }
  }
}

Poll the returned operation handle:

{
  "name": "flight_refund",
  "arguments": {
    "action": "status",
    "booking_ref": "JNK-ABC123",
    "booked_item_id": "itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a",
    "last_name": "Doe",
    "operation": "svc_01J7ZR5Q2KME8V4T"
  }
}

The operation’s state uses lowercase values: in_progress and attention_required are non-terminal; succeeded and failed are terminal. Keep polling when Jinko needs to resolve attention_required. Read the supplier outcome and money state before telling the customer the refund is complete.

preview cancels nothing. A legacy check call does not return a quote_id and cannot replace a preview. For a MANUAL_REQUIRED preview, follow the tool’s manual_ok instructions; omit acknowledged only when that preview carried no refund figure.

Introduction

Flights

Hotels

Cars

Trip & Payment

Marketing claim

Parameters

Examples

​Parameters

​Examples

Parameters

Examples