> ## Documentation Index > Fetch the complete documentation index at: https://docs.gojinko.com/llms.txt > Use this file to discover all available pages before exploring further. # flight-refund-preview > Preview what giving back a flight ticket would return to the customer Quote what the customer would get back for this ticket right now: the refund, the penalty in force, and every document the operation would cover. NOTHING is sent to the airline. `refund` is the customer figure, what they paid less the penalty; the supplier’s own net figures are under `provider_figures` and are not what the customer receives. 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, no supplier figure is read, and `provider_figures` is legitimately absent, 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. Use EXACTLY ONE: provider\_reference (the connector order id, the Sabre PNR or the TravelFusion reference, never the airline record locator), which additionally requires a credential that OWNS the booking, or booking\_ref + last\_name, which identifies it without one. Sending both is a 422. ## OpenAPI ````yaml api-reference/public-api.yaml POST /v1/flight_refund_preview openapi: 3.0.0 info: title: Jinko Public API version: 0.8.1 description: >- Curated public REST surface for Jinko. Authenticated with jnk_ API keys. See https://docs.gojinko.com for guides. ### Per-end-user attribution On booking calls you may send an optional `X-End-User-Id` request header to attribute the booking to one of your own end users (for per-end-user attribution and rate-limiting). The value is an **opaque, tenant-scoped** identifier that you choose — not a Jinko account id. Omit it to book as the tenant. WorkOS-shaped values (prefixed `user_` or `org_`) are rejected. servers: [] security: [] paths: /v1/flight_refund_preview: post: tags: - Post-booking summary: Preview what giving back a flight ticket would return to the customer description: >- Quote what the customer would get back for this ticket right now: the refund, the penalty in force, and every document the operation would cover. NOTHING is sent to the airline. `refund` is the customer figure — what they paid less the penalty; the supplier’s own net figures are under `provider_figures` and are not what the customer receives. 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, no supplier figure is read, and `provider_figures` is legitimately absent — 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. Use EXACTLY ONE: provider_reference (the connector order id — the Sabre PNR or the TravelFusion reference, never the airline record locator), which additionally requires a credential that OWNS the booking, or booking_ref + last_name, which identifies it without one. Sending both is a 422. requestBody: content: application/json: schema: $ref: '#/components/schemas/FlightRefundPreviewRequest' responses: '200': description: What giving the ticket back would return content: application/json: schema: $ref: '#/components/schemas/FlightRefundPreviewResponse' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: Malformed JSON in request body. doc_url: https://docs.gojinko.com/concepts/errors '401': description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: AUTH_REQUIRED message: Invalid or expired API key. doc_url: https://docs.gojinko.com/api-reference/authentication '402': description: Payment required — organization balance exhausted content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: PAYMENT_REQUIRED message: >- Insufficient balance — this call costs $0.0150 and your organization has $0.0000 available. Top up at https://dashboard.gojinko.com/developers/billing/topup doc_url: https://docs.gojinko.com/concepts/errors '404': description: Unknown booking, or one this credential may not read. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: booking not found '409': description: The operation conflicts with the current state of the resource content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: CONFLICT message: an exchange is already in progress for this booking doc_url: https://docs.gojinko.com/concepts/errors '410': description: The resource this request names no longer exists content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: GONE message: The resource no longer exists. doc_url: https://docs.gojinko.com/concepts/errors '422': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: BAD_REQUEST message: >- origins: origins is required; trip_type: trip_type is required doc_url: https://docs.gojinko.com/concepts/errors '429': description: Rate limit or quota exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: RATE_LIMITED message: Rate limit or quota exceeded. doc_url: https://docs.gojinko.com/concepts/errors '502': description: The travel provider rejected the request, or an upstream call failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_REJECTED message: >- sabre-rest BargainFinderMaxRQ failed with status 400: 27131 - Number of connection locations exceeds maximum allowed doc_url: https://docs.gojinko.com/concepts/errors '503': description: No travel provider can serve the request right now headers: Retry-After: description: >- Seconds to wait before retrying, forwarded verbatim from the upstream service. Absent when the upstream named no interval. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_UNAVAILABLE message: >- All flight providers are temporarily unable to serve this search. Please retry later. Provider reasons: sabre-rest: provider temporarily closed; travelfusion: quota exhausted doc_url: https://docs.gojinko.com/concepts/errors '504': description: The travel provider did not answer in time content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: UPSTREAM_TIMEOUT message: sabre-rest BargainFinderMaxRQ timed out after 30s doc_url: https://docs.gojinko.com/concepts/errors security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: FlightRefundPreviewRequest: type: object properties: provider_reference: type: string description: >- The CONNECTOR's own order id for this flight booking — the Sabre PNR for a Sabre booking, the TravelFusion booking reference for a TravelFusion one. NOT the airline record locator, which names the carrier's own copy of the reservation and is answered 404 here, identically to an unknown booking. OWNER mode: beyond the API authentication every call needs, this one requires a credential that OWNS the booking — a tenant-bound key reaches its whole tenant, any other credential must belong to the booking's own user. Mutually exclusive with booking_ref + last_name; sending both is rejected with 422. example: QQIUIQ booking_ref: type: string description: >- The Jinko reference. GUEST mode: pair it with last_name and the pair identifies the booking on its own — API authentication is still required, as on every call here, but the credential does not have to own the booking. Mutually exclusive with provider_reference; one without the other is rejected with 422. example: JNK-H1ZK90 last_name: type: string description: >- The lead traveller's surname. Required with booking_ref, and only with it. example: Carrard intent: $ref: '#/components/schemas/IntentInput' example: booking_ref: JNK-A0AUR2 last_name: Carrard FlightRefundPreviewResponse: type: object properties: quote: type: string description: >- This quote ("svq_…"). Pass it to POST /v1/flight_refund_commit — it binds the commit to the figures below. Opaque; the format may evolve. example: svq_01J7ZR3M8FKX2P9C state: type: string description: >- 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: type: boolean description: >- 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: $ref: '#/components/schemas/FlightServicingSupportLevel' manual_reason: type: string description: >- Why a person has to act. Present with `support_level: MANUAL_REQUIRED`. example: fare rules require agent review operation_kind: allOf: - $ref: '#/components/schemas/FlightOperationKind' - description: >- 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, the penalty is zero and `provider_figures` is absent. 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: type: string description: >- 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: type: string description: >- 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' item: type: string description: >- The booked item this quote covers ("itm_…"). 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 provider: type: string description: Which supplier the operation would be sent to. Informational. example: sabre-rest refund: type: object properties: value: type: integer description: >- 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. example: 41250 amount: type: number description: >- 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). currency: type: string description: ISO 4217 currency code. example: USD decimal_places: type: integer description: >- 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. example: 2 basis: type: string description: >- 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. example: sell_minus_penalty description: >- 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, never `provider_figures`. Absent is not zero: a quote whose penalty is unknown carries no refund figure at all. penalty: type: object properties: value: type: integer description: >- 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. example: 41250 amount: type: number description: >- 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). currency: type: string description: ISO 4217 currency code. example: USD decimal_places: type: integer description: >- 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. example: 2 fee_known: type: boolean description: >- 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. example: true description: >- What the customer would forfeit, in the currency they were charged. Zero on a void. Read `fee_known` before showing it — false means UNKNOWN, not free. documents: type: array items: $ref: '#/components/schemas/FlightDocument' description: >- Every document this operation covers, each of them active right now. Ticket subsets are not offered: the operation takes the whole item. ancillary_recoverable: type: boolean description: >- 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 provider_figures: $ref: '#/components/schemas/FlightProviderFigures' not_commitable_reason: type: string description: >- Why `commitable` is false. Today: `manual_required` (a Jinko agent has to act — resubmit with `manual_ok: true`), `provider_unsupported` (the airline offers no refund through the API), `not_cancellable` (this ticket cannot be given back as it stands), `penalty_exceeds_sell` (the penalty is at least what the customer paid), `multi_currency_basis` (the booking was paid across currencies and no single refund figure exists), `funds_unavailable` (the original payment cannot cover the refund yet), `insufficient_time_to_converge` (too little time is left to finish before the flight). New reasons may be added, so treat an unrecognised value as "not right now". example: not_cancellable ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - AUTH_REQUIRED - PAYMENT_REQUIRED - RATE_LIMITED - BAD_REQUEST - FORBIDDEN - NOT_FOUND - CONFLICT - GONE - QUOTE_EXPIRED - TRIP_EXPIRED - TRIP_STATE_CONFLICT - OFFER_EXPIRED - OFFER_UNAVAILABLE - MISSING_CUSTOMER_DETAILS - CURRENCY_UNSUPPORTED - UPSTREAM_REJECTED - UPSTREAM_UNAVAILABLE - UPSTREAM_TIMEOUT - UPSTREAM_ERROR - INTERNAL description: >- What went wrong, as a stable machine-readable code. This is a closed set — branch on it rather than on `message`, which is prose and may change. New codes arrive in a minor version, so treat an unknown one as its HTTP status. A code can also stop being emitted: it leaves this set in a minor version, named in the changelog, and a branch you wrote for it goes unreached rather than wrong. example: BAD_REQUEST message: type: string doc_url: type: string required: - code - message required: - error IntentInput: type: object properties: user_intent: type: string nullable: true description: >- The user's natural-language intent: the Alpic PII-stripped paraphrase when available, else a best-effort fallback to the client-provided NL query. example: find a cheap flight to Tokyo FlightServicingSupportLevel: type: string enum: - AUTO - AUTO_VOID - MANUAL_REQUIRED description: >- 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. FlightOperationKind: type: string enum: - cancel - void description: >- What the platform would do, or did. `cancel` — refund the ticket under the fare rules, less the penalty. `void` — the ticket is inside its void window, so it is voided and the original charge is reversed in full, penalty-free. The platform decides from the live state of the documents; the caller cannot ask for one. FlightDocument: type: object properties: number: type: string description: The 13-digit ticket or EMD number. example: '0012345678901' type: type: string enum: - TKT - EMD description: >- 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: type: string enum: - ACTIVE - REFUNDED - VOIDED - INACTIVE - PENDING - UNKNOWN description: >- 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). example: ACTIVE recoverable: type: boolean description: >- 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. example: false FlightProviderFigures: type: object properties: refund_net: type: object properties: amount: type: number description: >- 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: type: integer description: >- 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. example: 41250 currency: type: string description: ISO 4217 currency code. example: USD decimal_places: type: integer description: >- 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. example: 2 penalty_net: type: object properties: amount: type: number description: >- 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: type: integer description: >- 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. example: 41250 currency: type: string description: ISO 4217 currency code. example: USD decimal_places: type: integer description: >- 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. example: 2 currency: type: string example: USD total_paid_net: type: object properties: value: type: integer description: >- 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. example: 41250 amount: type: number description: >- 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). currency: type: string description: ISO 4217 currency code. example: USD decimal_places: type: integer description: >- 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. example: 2 description: >- What the airline recorded as paid to it for this item, net of Jinko’s margin. The base `refund_net` is measured against, and not what the customer paid. description: >- The airline's own net figures, for reconciliation — never what the customer receives. `refund_net` is what the airline returns to Jinko, `penalty_net` what it withheld from Jinko and `total_paid_net` what it recorded as paid to it; on a ticket sold at a margin all three differ from the customer figures. Show the customer the top-level `refund_amount` / `refund`, never these. `currency` is the currency the airline settles in, which can differ from the currency charged. The whole object is omitted on a void (`operation_kind: void`): the original charge is reversed without reading any supplier figure, so there is none to report. securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key BearerAuth: type: http scheme: bearer ````