Skip to main content
POST
Preview what cancelling a booked flight (every ticket on the item) would return to the customer
Quote what the customer would get back for this flight item, every ticket on it, right now: the refund, the penalty in force, and every document the operation would cover. NOTHING is sent to the airline. refund is what the customer paid less the penalty. All amounts are customer-facing only. The platform decides WHICH operation this is and reports it as operation_kind: a ticket still inside its void window is void, the entire charge is reversed, penalty-free, and anything else is cancel, a refund under the fare rules. You cannot ask for one; read what you are given, because the void window closes with time. commitable: false with support_level: MANUAL_REQUIRED is not a dead end: the commit takes manual_ok: true and hands the operation to a Jinko agent. The handle this returns is named quote: it is what POST /v1/flight_refund_commit consumes, and it stops binding at expires_at. Every call here needs API authentication; this is about which mode identifies the booking. Call get_booking first, then send booking_ref and the selected booked_item_id. Guests must send last_name; owning credentials may omit it. The deprecated provider, order_id, provider_reference and provider_booking_id are accepted until 2027-04-30 where the request declares them; a request that sends one is answered with Deprecation and Sunset headers.

Authorizations

​
X-API-Key
string
header
required

Body

application/json
​
booking_ref
string

Jinko booking reference. Call get_booking first, then select its booked_item_id for servicing.

Minimum string length: 1
Example:

"JNK-A0AUR2"

​
booked_item_id
string

The booked item, from get_booking items[].booked_item_id. Preserved across exchanges. Omit only when the booking has exactly one item of the requested domain; otherwise a 409 returns items to choose from.

Pattern: ^itm_[a-z2-7]+$(?![\s\S])
Example:

"itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a"

​
last_name
string

Required for guest lookup. A credential that owns the booking may omit it; ownership is checked by the platform.

Minimum string length: 1
Example:

"Doe"

​
provider_reference
string
deprecated

Deprecated: name the booking with booking_ref and booked_item_id from get_booking. Names the booking instead of booking_ref and last_name, never beside it, and needs a credential that owns the booking. Accepted until 2027-04-30; a request that sends it is answered with Deprecation and Sunset headers.

Minimum string length: 1
​
intent
object

Response

What cancelling the flight item would return

​
seat_refunds
object[]

Separate refunds for carrier-settled paid seats. A paid seat is refunded once the airline refunds Jinko; these amounts are not part of the quoted fare refund.

​
quote_id
string

This quote. Pass it as quote_id to POST /v1/flight_refund_commit — it binds the commit to the figures below. Opaque; the format may evolve.

Example:

"svq_01J7ZR3M8FKX2P9C"

​
quote
string
deprecated

Deprecated: use quote_id instead. Same value.

Example:

"svq_01J7ZR3M8FKX2P9C"

​
state
string

Lifecycle of the QUOTE, not of a refund — nothing has been refunded or voided by this call. completed means the figures are final until expires_at.

Example:

"completed"

​
commitable
boolean

Whether a commit against this quote would be accepted as it stands. A MANUAL_REQUIRED quote is never commitable and is still SUBMITTABLE: send the commit with manual_ok: true to hand it to a Jinko agent. Otherwise, when false, not_commitable_reason says why and committing is pointless.

Example:

true

​
support_level
enum<string>

How this refund would be carried out. AUTO — the platform refunds the ticket end to end under the fare rules. AUTO_VOID — the ticket is still inside the airline's void window, so the platform voids it and the ENTIRE charge is reversed, penalty-free; there is no supplier figure to report on a void. MANUAL_REQUIRED — it is possible, but a Jinko agent has to act (manual_reason says why): the commit is refused unless you send manual_ok: true, which hands it to that agent. Do not treat MANUAL_REQUIRED as a failure. Time-sensitive: a void window closes, so read the level from a live preview.

Available options:
AUTO,
AUTO_VOID,
MANUAL_REQUIRED
​
manual_reason
string

Why a person has to act, in words the customer can be shown. Present with support_level: MANUAL_REQUIRED. Where the reason would be the supplier’s own words, it reads “This request needs manual handling by Jinko support.”

Example:

"fare rules require agent review"

​
operation_kind
enum<string>

What this quote would do — refund the ticket under the fare rules (cancel) or void it (void). On a void the whole charge comes back and the penalty is zero. The status read reports the operation that actually ran under this same name, so the two compare directly. The handle that binds this quote is quote; operation is the "svc_…" handle the COMMIT answers, and it never appears on a quote.

Available options:
cancel,
void
​
settlement_basis
string

How the refund is settled. sell_minus_penalty — what the customer paid for this ticket, less the penalty (a cancellation). original_charge — the whole charge is reversed, penalty-free (a void). It follows operation_kind, which the platform derives; the caller cannot ask for one.

Example:

"sell_minus_penalty"

​
expires_at
string

When this quote stops binding. Committing after it answers 409 QUOTE_EXPIRED; take a fresh quote and show the customer the new figure before committing again.

Example:

"2026-09-03T12:15:00Z"

​
booked_item_id
string

The booked item this quote covers — the booked_item_id get_booking returns. A booking holding several items is quoted and refunded one item at a time; within an item, every ticket issued for it is covered together.

Example:

"itm_7f2c9a4e8b1d"

​
item
string
deprecated

Deprecated: use booked_item_id instead. Same value.

Example:

"itm_7f2c9a4e8b1d"

​
refund
object

THE CUSTOMER FIGURE: what would go back to the payment method, on the basis named in basis — what they paid less the penalty, or the entire charge on a void. Show this one. Absent is not zero: a quote whose penalty is unknown carries no refund figure at all.

​
penalty
object

What the customer would forfeit, in the currency they were charged. Zero on a void. May be omitted when unknown; absent is not zero. Read fee_known before showing it — false means UNKNOWN, not free.

​
documents
object[]

Every document this operation covers, each of them active right now. Ticket subsets are not offered: the operation takes the whole item.

​
ancillary_recoverable
boolean

Whether the ancillaries bought with this ticket come back with it. false when any document is an EMD — the platform cannot refund or void one, so that value has to be recovered by a person, and the quote is MANUAL_REQUIRED. Tell the customer before they commit, not after.

Example:

true

​
not_commitable_reason
string

Why commitable is false. Today: manual_required (a Jinko agent has to act — resubmit with manual_ok: true; manual_reason says why), penalty_exceeds_sell (the penalty is at least what the customer paid), multi_currency_basis (the airline prices the refund in a currency the customer was not charged in, so no single figure exists). Two refusals are never values here: a fare the airline will not refund is 409 not_cancellable from this preview itself, and an airline with no refund route is 422 provider_unsupported. The contract reserves further values (provider_unsupported, funds_unavailable, insufficient_time_to_converge) and new reasons may be added, so treat an unrecognised value as "not right now".

Example:

"manual_required"