--- title: "Preview what cancelling a booked flight (every ticket on the item) would return to the customer" method: POST path: "/v1/flight_refund_preview" tags: ["Post-booking"] --- # Preview what cancelling a booked flight (every ticket on the item) would return to the customer `POST /v1/flight_refund_preview` ## Request - Base URL: `https://api.gojinko.com` - URL: `https://api.gojinko.com/v1/flight_refund_preview` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer 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. ## Request body - FlightRefundPreviewRequest - `booking_ref` string: Jinko booking reference. Call get_booking first, then select its booked_item_id for servicing. - `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. - `last_name` string: Required for guest lookup. A credential that owns the booking may omit it; ownership is checked by the platform. - `provider_reference` string: 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. - `intent` IntentInput - `user_intent` string, nullable: The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query. ## Response `200` What cancelling the flight item would return - FlightRefundPreviewResponse - `seat_refunds` SeatRefund[]: 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. - `offer_id` string, required - `seat_number` string, required - `traveler_ref` string - `pax_ref_id` string: Deprecated: use `traveler_ref` instead. Same value. - `status` 'pending_airline_refund' | 'refunded' | 'not_refunded', required - `amount` object, required: The seat price while pending, then the actual customer refund amount (zero when not refunded). Not part of the separate quoted fare refund. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `carrier` string, required: Airline display name. - `message` string, required: Customer-facing sentence explaining the seat refund. - `airline_refund_registered` boolean, required: Whether the airline refund has been registered with the payment provider. - `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. - `quote` string: Deprecated: use `quote_id` instead. Same value. - `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`. - `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. - `support_level` 'AUTO' | 'AUTO_VOID' | 'MANUAL_REQUIRED': 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. - `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.” - `operation_kind` 'cancel' | 'void': 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. - `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. - `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. - `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. - `item` string: Deprecated: use `booked_item_id` instead. Same value. - `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. - `amount` number: Deprecated: use `amount_money` instead. Alternative to `value` on some endpoints (the two never appear together); its scale depends on decimal_places. When this object carries decimal_places, amount is an INTEGER in minor units — divide by 10 ** decimal_places (e.g. select_ancillaries total_with_ancillaries). When there is no decimal_places field, amount is a decimal in MAJOR units, safe to display as-is (e.g. trip and checkout totals). - `value` integer: Deprecated: use `amount_money` instead. Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: Deprecated: use `amount_money` instead. ISO 4217 currency code. - `decimal_places` integer: Deprecated: use `amount_money` instead. Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `amount_money` object: The refund figure. Absent when the figure is not known. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `basis` string: How the figure was computed. `sell_minus_penalty` — what the customer paid for this item, less the penalty. `original_charge` — the entire charge is reversed, penalty-free (a void). The platform chooses; the caller cannot ask for one. - `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. - `amount` number: Deprecated: use `amount_money` instead. Alternative to `value` on some endpoints (the two never appear together); its scale depends on decimal_places. When this object carries decimal_places, amount is an INTEGER in minor units — divide by 10 ** decimal_places (e.g. select_ancillaries total_with_ancillaries). When there is no decimal_places field, amount is a decimal in MAJOR units, safe to display as-is (e.g. trip and checkout totals). - `value` integer: Deprecated: use `amount_money` instead. Integer amount in MINOR units, always paired with decimal_places — divide by 10 ** decimal_places to display. Example: value 15977 with decimal_places 2 is 159.77 USD. Rendering this field directly shows prices 100x too high for 2-decimal currencies. - `currency` string: Deprecated: use `amount_money` instead. ISO 4217 currency code. - `decimal_places` integer: Deprecated: use `amount_money` instead. Scale of the integer value/amount: display = integer / 10 ** decimal_places. Always sent alongside minor-unit amounts. Usually the ISO 4217 digits of the currency (2 for USD/EUR/GBP, 0 for JPY/KRW, 3 for BHD/JOD/KWD) but currency-converted prices can carry a different scale — ALWAYS use the decimal_places sent with the amount, never a hardcoded 2. Only if the field is genuinely absent on a value-shaped object, fall back to the ISO digits for the currency. - `display` string: Deprecated: use `amount_money` instead. The same figure as a string ready to show: the ISO 4217 code, a space, then the amount, e.g. "USD 159.77". With decimal_places it is written at exactly that scale (value 1561500, JPY, decimal_places 2 is "JPY 15615.00"); without, at the ISO digits of the currency. Show this; compute with the number. Absent when the figure is not money (a cancellation step expressed as a percent or a number of nights) or could not be read unambiguously. - `amount_money` object: The penalty figure. Present only when `fee_known` is true; absent when the fee is unknown, which is not zero. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `fee_known` boolean: false means the penalty could not be established — UNKNOWN, not zero. Render it as "we will confirm the fee", never as free cancellation, and expect the final figure on the operation status. - `breakdown` object: How the supplier itemises the penalty, in the same currency: the airline’s cancellation fee, the taxes it does not give back, and the fare of flights already flown. Present when the supplier states at least one of them; a member the supplier does not state is absent, and a stated zero is a zero. The penalty figure is what is withheld; the members explain it and may not add up to it exactly (each is converted and rounded on its own, and a supplier may withhold something it does not itemise). - `airline_fee` object: The airline’s cancellation fee, taxes on the fee included. This is the figure a fare rule advertises. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `non_refundable_taxes` object: The taxes and carrier surcharges the airline does not give back, summed. On a ticket refunded after part of it was used, this includes the taxes of the flights already flown. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `used_fare` object: The fare of the flights already flown, on a ticket that is refunded after part of it was used. - `value` integer, required: Integer amount in MINOR units at the ISO 4217 digits of `currency`: divide by 10 ** decimal_places to get the amount. Signed where the field says so (a price change delta). - `currency` string, required: ISO 4217 currency code. - `decimal_places` integer, required: The ISO 4217 digits of `currency` (2 for USD/EUR, 0 for JPY/KRW, 3 for BHD/KWD), and the scale of `value`. - `display` string, required: The same figure as a string ready to show: the ISO 4217 code, a space, then the amount at `decimal_places`, e.g. "USD 412.50". Show this; compute with `value`. - `documents` FlightDocument[]: Every document this operation covers, each of them active right now. Ticket subsets are not offered: the operation takes the whole item. - `number` string: The 13-digit ticket or EMD number. - `type` 'TKT' | 'EMD': What the document is. `TKT` — the flight ticket itself. `EMD` — an electronic miscellaneous document, which is how an ancillary (a bag, a seat) is issued. - `state` 'ACTIVE' | 'REFUNDED' | 'VOIDED' | 'INACTIVE' | 'PENDING' | 'UNKNOWN': Where the document itself has got to. Every document on a preview is `ACTIVE` — that is what makes the quote possible. On a status read the values are the outcome per document: `REFUNDED`, `VOIDED`, `INACTIVE` (the airline dropped it), `PENDING` (the airline has not settled it) or `UNKNOWN` (not yet observed). - `recoverable` boolean: Whether this document’s value can be recovered through this path. `false` on every EMD: the platform has no EMD refund or void operation, so an ancillary issued as one is not returned by this operation and a person has to recover it. - `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. - `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". ## Other responses - `400`: Bad request - `401`: Authentication required - `402`: Payment required — organization balance exhausted - `404`: Unknown booking, or one this credential may not read. - `409`: The airline will not refund this item as it stands — a non-refundable fare, or every document already voided or refunded. A booking that is no longer active is also refused with `reason_code: booking_not_active` when the caller may service it (any other caller gets the same 404 as for an unknown booking). `code` is `not_cancellable`, as a sibling of `error`. `error.message` is “This booking cannot be cancelled online. Contact Jinko support.” when the airline refused, or the platform’s sentence when the booking is no longer active. There is no quote to show, nothing to commit, and `manual_ok` does not apply. Another operation already in flight on the item (an exchange, a refund or a cancellation) is refused the same way, with `code: active_operation_exists` and `active_operation` naming it: follow it with the status route and preview again once it has finished. A manual request no Jinko agent has picked up yet does not block a preview. A 409 with no `code` beside `error` is not this case — the reference matched more than one booking, or the booking holds several flights and `item_id` named none. - `410`: The resource this request names no longer exists - `422`: Validation error - `429`: Rate limit or quota exceeded - `502`: The travel provider rejected the request, or an upstream call failed - `503`: No travel provider can serve the request right now - `504`: The travel provider did not answer in time --- [API](https://skmtc.dev/gojinko/apis/jinko-public-api.md) - [All operations](https://skmtc.dev/gojinko/apis/jinko-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gojinko/apis/jinko-public-api/revisions/ac5046767e4c?raw)