--- title: "Commit a flight exchange" method: POST path: "/v1/exchange_commit" tags: ["Post-booking"] --- # Commit a flight exchange `POST /v1/exchange_commit` ## Request - Base URL: `https://api.gojinko.com` - URL: `https://api.gojinko.com/v1/exchange_commit` - Auth: one of: - API key in header `X-API-Key` - HTTP bearer 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 - ExchangeCommitRequest - `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. - `offer_id` string, required - `quote_id` string: The `quote_id` exchange_price returned. Not required. Optional after a refused exchange price, when committing the same offer to request manual handling. ## Response `200` Commit a flight exchange - ExchangeCommitResponse - `airline_locator` string: Deprecated: read the item’s `supplier_references` on POST /v1/get_booking, which carries each airline’s record locator with the airline that issued it. Airline record locator for the current itinerary. - `booking_ref` string - `booking_reference` string: Deprecated: use `booking_ref` instead. Same value. - `new_ticket_numbers` string[] - `status` 'confirmed' | 'pending' | 'partial_failure' | 'failed': A commit answers `pending`: the exchange is carried out after this call, whatever the payment outcome. Follow it with exchange_status until it reads `confirmed`, `partial_failure` or `failed`. - `payment_outcome` 'EVEN' | 'ADD_COLLECT' | 'REFUND': `ADD_COLLECT` — the customer pays the difference first: send them to `checkout_url`; the exchange runs only after that payment authorizes. `EVEN` — nothing to pay. `REFUND` — the difference goes back to the original payment method once the exchange completes. - `checkout_url` string: Present when `payment_outcome` is `ADD_COLLECT`: the page where the customer pays the difference. Nothing is exchanged until that payment authorizes. exchange_status returns the same page while the exchange waits for it. - `stripe_checkout_session_url` string: Deprecated: use `checkout_url` instead. The same payment page, under a provider’s name. - `warnings` string[]: Notes about the booking and its documents, each said once, in words the customer can be shown. A note the supplier sends as free text without a code is left out. ## Other responses - `400`: The supplier refused the request when the commit priced the offer again (an expired or malformed offer, a leg selection it cannot serve), with the message “This exchange cannot be processed as requested. Change the selected flights or contact Jinko support.” Nothing was exchanged or charged; shop again. **`INVALID_EXCHANGE_REQUEST`** — The supplier refused the exchange request itself. Change the selected flights, or contact Jinko support. The refusal does not say which part of the request was refused. **`INVALID_SEGMENTS_TO_EXCHANGE`** — An exchange selection does not match a booked leg. Read the booking and select each leg by its booked origin and destination. **`PARTIAL_EXCHANGE_UNSUPPORTED`** — The supplier cannot keep unselected legs unchanged for this booking. Name every booked leg in segments_to_exchange to reshop the whole itinerary. - `401`: Authentication required - `402`: Payment required — organization balance exhausted - `404`: Resource not found - `409`: Nothing was exchanged or charged by this call. `code` says why — see `ExchangeCommitConflictCode`. On `funds_unavailable`, `multi_currency_basis` and `manual_required` the exchange can't be refunded automatically, so the request has been sent to Jinko support, who will complete it and refund the customer; follow it on `get_booking` at `items[].servicing.exchange`. On `exchange_in_progress` an exchange for this booking is already waiting for payment or running: call exchange_status for its progress and its `checkout_url`. On `not_exchangeable` the booking cannot be exchanged as it stands (no ticket or flight left to change, or a fare that does not permit it); nothing is sent to support. Choose `item_id` when several booked items match. A 409 whose `code` is outside that list arrives as the plain error envelope. - `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)