---
title: "Check how a flight refund or void ended"
method: POST
path: "/v1/flight_refund_status"
tags: ["Post-booking"]
---

# Check how a flight refund or void ended

`POST /v1/flight_refund_status`

## Request

- Base URL: `https://api.gojinko.com`
- URL: `https://api.gojinko.com/v1/flight_refund_status`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Report where one refund or void has got to, named by the `operation` handle a commit (or POST /v1/refund_commit) returned. Read-only. `state` is the platform view — keep polling while it is `in_progress` or `attention_required`, both of which mean the operation is still alive; `attention_required` means a Jinko agent has it, and `park_deadline` says how long that lasts. `operation_kind` says which operation actually ran. `provider` is what the airline says, including what became of each ticket and EMD — an operation has done its work when every document it covers has reached a terminal state. `money` is where the refund itself has got to; the two move independently, so the tickets can read refunded while the money is still in flight. Do not tell a customer they have been refunded until `money.vehicle_state` says `paid`. Same auth modes as flight_refund_preview.

## Request body

- FlightRefundStatusRequest
  - `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.
  - `operation` string, required: The "svc_…" handle from a commit, or from POST /v1/refund_commit.

## Response `200`

Where the refund or void has got to

- FlightRefundStatusResponse
  - `operation` string
  - `state` 'in_progress' | 'attention_required' | 'succeeded' | 'failed': Where the cancellation has got to. `in_progress` — running; keep polling. `attention_required` — stalled on something a person at Jinko has to resolve (`reason` names it); keep polling, and do not report it to the customer as a failure, because the booking may already be cancelled at the supplier. `succeeded` and `failed` are terminal: the supplier outcome and the money are both settled and nothing further will change.
  - `reason` string: With `state: attention_required`, why the operation is stalled: the value names what Jinko has to resolve, and needs nothing from the caller. With `state: failed`, why it ended: `provider_refused` (the supplier refused before changing anything), `provider_did_not_apply` (the supplier’s record shows it was not applied), `not_sent` (it ended before anything was sent to the supplier), `QUOTE_EXPIRED` (the quote it was committed on no longer stood), `superseded` or `not_cancellable`. Absent on a failed operation that recorded none.
  - `message` string: A sentence about why a failed operation ended, where there is one: what the supplier’s refusal means, or that its price changed after the quote. Present only with `state: failed`; it never states the supplier’s figures.
  - `park_deadline` string: When a parked operation stops waiting for Jinko and is settled or failed. Present with `state: attention_required`; it is how long "keep polling" lasts.
  - `next_run_at` string: When the platform next drives this operation by itself. Informational — polling sooner does not make it run sooner.
  - `provider` object: The airline's record. It can show the tickets refunded while the money is still moving — that is the normal middle of a refund, not a discrepancy.
    - `state` string: The supplier's own view of the booking: `confirmed` (still standing), `cancelled`, or `pending` (the supplier has not settled it yet).
    - `references` object
      - `cancellation_reference` string: The reference the supplier issued for the cancellation or refund itself, for example the ticket number a void settles or the supplier’s refund id. It is never the supplier’s identifier for the booking, and is absent when the supplier issued none.
    - `documents` FlightDocument[]: What each document the operation covers was last observed to be. Absent until the first probe. This is the proof of what happened: an operation has done its work when every document it covers has reached a terminal state, not when a refund record appears.
      - `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.
  - `money` object: The refund and where it has got to. Read `vehicle_state` before telling a customer they have been refunded.
    - `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 figure being moved.
      - `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`.
    - `direction` string: Which way the money moves. `refund` on a cancellation.
    - `vehicle_state` string: How far the money itself has got, independently of the supplier: `reserved` (earmarked, nothing sent), `refund_pending` (submitted to the payment provider), `payout_initiated` and `payout_settled` (paid out to a third party), `paid` (it has reached the customer), `released` (earmark dropped, nothing owed), `refund_review` (a person at Jinko has to release it). Only `paid` and `payout_settled` mean the customer has the money.
    - `stripe_reference` string: Deprecated. An internal payment reference.
  - `operation_kind` 'cancel' | 'void': Which operation ran — a refund under the fare rules (`cancel`) or a void of the original charge (`void`). The same field the preview quoted, so what was quoted and what ran compare directly.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `402`: Payment required — organization balance exhausted
- `404`: Unknown operation or booking, or one this credential may not read.
- `409`: Several booked items match. Select a booked_item_id from items and repeat with booking_ref and booked_item_id.
- `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)