--- title: "Refund or void a booked flight (every ticket on the item) against a quote the customer accepted" method: POST path: "/v1/flight_refund_commit" tags: ["Post-booking"] --- # Refund or void a booked flight (every ticket on the item) against a quote the customer accepted `POST /v1/flight_refund_commit` ## Request - Base URL: `https://api.gojinko.com` - URL: `https://api.gojinko.com/v1/flight_refund_commit` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer Start the operation the preview described — a refund, or a void of the original charge, whichever the preview reported as `operation_kind`. The body is the `quote` handle and the `acknowledged` figure PLUS the same auth mode the preview took: ownership is re-checked here rather than carried by the handle, so the mode has to be sent again. `acknowledged` is the refund the customer was shown, copied from the preview as it arrived (`value` and `decimal_places` included): if your figure differs from the still-live quote’s refund, the call is refused with 409 `quote_drift`. `retry_quote_id` is that same quote’s handle and `current.refund` its figure. Show it to the customer, then commit again with that handle and figure. Nothing is sent to the airline. A MANUAL_REQUIRED quote needs `manual_ok: true`: the operation is then raised for a Jinko agent and answers `attention_required` with `reason: manual_required`, again without the airline being called. Committing one without the flag is refused 409 `manual_required`. That submission is also the one case where `acknowledged` may be left out: a MANUAL_REQUIRED quote whose penalty is unknown carries no `refund` to acknowledge, and there is nothing to compare against. Whenever the preview DID name a refund, send it. The other refusals are 409 `QUOTE_EXPIRED` (preview again), `active_operation_exists` (poll the `active_operation` when present instead of starting a second one), `not_cancellable`, `funds_unavailable`, `superseded`, and — when the preview already said `commitable: false` and you committed anyway — that quote’s own reason answered back as the code: `penalty_exceeds_sell` or `multi_currency_basis`. Success does NOT mean the money has moved: giving the tickets back at the airline and returning the money to the customer are separate steps, so the answer is an `operation` handle to poll with POST /v1/flight_refund_status. ## Request body - FlightRefundCommitRequest - `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. - `quote_id` string, required: The `quote_id` from a preceding POST /v1/flight_refund_preview. Binds this commit to the figures that quote reported. - `acknowledged` object: The refund the customer was shown — copy the preview's `refund.amount_money` across. Copying the whole `refund` object, as older integrations do, is still accepted. REQUIRED whenever the preview carried a `refund`, which is every quote that names a figure. It may be omitted in exactly one case: a MANUAL_REQUIRED quote that carries no `refund` at all because the penalty is unknown (`penalty.fee_known: false`), submitted with `manual_ok: true` — there is no figure to acknowledge, and inventing one would have the customer agree to a number nobody computed. Omitting it anywhere else is refused by the platform, not here. When present, all three of `value` (minor units), `currency` and `decimal_places` are required: the platform compares this against the refund as it stands, and a figure whose scale is unstated cannot be compared. `amount` is not accepted in its place. Any other key, such as `display` or `basis`, is ignored. A mismatch against a still-live quote’s refund is answered 409 `quote_drift`. `retry_quote_id` is that same quote’s handle and `current.refund` its figure. Show it to the customer, then commit again with that handle and figure. Nothing is sent to the airline. - `value` integer, required: 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, required: ISO 4217 currency code. - `decimal_places` integer, required: 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. - `manual_ok` boolean: Send `true` to submit a quote whose `support_level` is MANUAL_REQUIRED. The operation is then raised for a Jinko agent and answers `state: attention_required` with `reason: manual_required` — NOTHING is sent to the airline by this call, and the agent settles or fails it. Without the flag such a commit is refused 409 `manual_required`, so a customer is never put in an agent queue unasked. On an AUTO or AUTO_VOID quote the flag changes nothing. This is also the one submission that may carry no `acknowledged` figure — when the quote itself named none, because the penalty is unknown. ## Response `200` The refund or void was accepted and is running - FlightRefundCommitResponse - `operation` string: The operation this call started ("svc_…"). Poll it with POST /v1/flight_refund_status; it is the only handle that reports how the airline call and the refund ended. - `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: Why the operation is parked, when `state` is `attention_required`. On a commit that is `manual_required`: you sent `manual_ok: true`, a Jinko agent now has it, and nothing has been sent to the airline. Not a failure — poll the operation. ## 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 commit cannot run as quoted; nothing was sent to the airline. `code` says which case, as a sibling of `error` — see `FlightServicingConflictCode` for the closed list and what each one asks of you. A booking that is no longer active is refused with `code: not_cancellable`, `reason_code: booking_not_active` and a platform sentence in `error.message`, when the caller may service it. A 409 whose `code` is outside that list is NOT a servicing refusal: it arrives as the plain error envelope, with no `code` beside it. - `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)