--- title: "DEPRECATED — use /v1/flight_refund_commit. Initiate a refund for a booked flight" method: POST path: "/v1/refund_commit" tags: ["Post-booking"] deprecated: true --- # DEPRECATED — use /v1/flight_refund_commit. Initiate a refund for a booked flight `POST /v1/refund_commit` ## Request - Base URL: `https://api.gojinko.com` - URL: `https://api.gojinko.com/v1/refund_commit` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer > **Deprecated.** Call get_booking first. Use booking_ref and the selected booked_item_id for every servicing action. last_name is required for guest lookup; an owning credential 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. A 409 item_selection_required returns safe items to choose from. ## Request body - RefundCommitRequest - `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. - `order_id` string: Deprecated: name the booking with booking_ref and booked_item_id from get_booking. Names the booking instead of booking_ref, 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. - `provider` string: Deprecated: omit it. The platform uses the supplier recorded with 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` Initiate a refund for a booked flight - RefundCommitResponse - `refund_status` 'PENDING' | 'IN_PROGRESS' | 'SUCCEEDED' | 'FAILED' | 'MANUAL_REQUIRED' | 'UNCONFIRMED' | 'CANCELLED': The refund's processing status. `PENDING` and `IN_PROGRESS` mean it is still running — poll `operation`. `MANUAL_REQUIRED` means a Jinko agent has it: raised, parked, NOT failed. `UNCONFIRMED` means the airline has not settled its answer yet. `SUCCEEDED`, `FAILED` and `CANCELLED` are terminal. `state` beside it reports the same operation in the platform vocabulary; either is enough to decide whether to keep polling. - `operation` string: The refund this call started ("svc_…"). Refunding at the airline and returning the money to the customer's card are separate steps, so this call answering does not mean both finished — poll the handle with POST /v1/flight_refund_status until `state` is terminal. - `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. - `operation_kind` 'cancel' | 'void': 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. - `refund_amount` object: THE CUSTOMER FIGURE: what goes back to the payment method that paid for this ticket — what they paid, less the penalty, or the whole charge when the ticket was voided (`operation_kind: void`). All amounts are customer-facing only. Absent is not zero. - `amount` number: Deprecated: use `value` instead (the same integer) where this object carries decimal_places. Where it does not, the figure is in MAJOR units and the field holding this object is itself deprecated: read its `*_money` sibling. The two-scale rule applies only to deprecated fields. 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: 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: ISO 4217 currency code. - `decimal_places` integer: 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: 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. - `refund_reference` string - `warnings` string[] ## Other responses - `400`: Bad request - `401`: Authentication required - `402`: Payment required — organization balance exhausted - `404`: Resource not found - `409`: Servicing refusal or booking item selection required. A booking returned by get_booking with status failed (for example, after payment), expired_quote, pending or exchange_partial_failure is refused with `code: not_cancellable`, `reason_code: booking_not_active` and a platform sentence in `error.message`, when the caller may service the booking. Any other caller gets the same 404 as for an unknown booking. - `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)