get_booking, select the flight item, then shop for exchange options and price the chosen offer. Show the traveler the new itinerary, fare conditions and the amount to pay or receive before asking them to confirm. Keep the same booking_ref and booked_item_id throughout the exchange.
See Flight Exchange for the MCP workflow and exchange commit for the REST operation.
Choose the legs to change
get_booking lists the flight item’s legs, each with its first departure and final arrival airport. Name each leg to change by those two airports, with its new date, in segments_to_exchange; legs you do not name stay as booked. To move only the return of a round trip, name only the return. A leg that has already departed can stay as booked, but cannot be named.
The platform checks the selection against the booking before asking the airline. Each refusal below lists the booked legs in its message; an entry that is malformed (a field of the wrong type, or a date not written YYYY-MM-DD) answers INVALID_SEGMENTS_TO_EXCHANGE without them:
On REST,
preferred_departure_date is still accepted. It moves the first leg to that date and reshops every leg, so use it only for a booking with a single leg. The MCP tool takes segments_to_exchange only.
When the customer pays the difference
When pricing answersADD_COLLECT, committing does not change the ticket yet. The commit returns the payment page (checkout_url). Send the customer there; the exchange is carried out once that payment authorizes. While it waits, the exchange status reads pending and returns the same page, so you can send it again if it was lost, and a second commit is refused with exchange_in_progress and starts nothing.
The page takes the payment for up to one hour, or until the new fare’s own deadline when that comes sooner. While the exchange waits, the booking cannot be refunded, cancelled or exchanged in another way. If the customer has not paid by then, the exchange is cancelled within a minute: its status reads failed with the reason, the page no longer works, nothing is charged and the booking is unchanged. From then on the booking can be exchanged, refunded or cancelled again; a new commit starts a new exchange with a new page.
When the booking cannot be exchanged
NOT_EXCHANGEABLE means the booking cannot be exchanged as it stands: no ticket or flight is left to change, or the fare does not permit the change. Shopping answers it as error.code; pricing and committing answer CONFLICT with the sibling code: "not_exchangeable". Any of the three can refuse, for example after the ticket was voided between the price and the commit; nothing is exchanged or charged. Its message is fixed, “This booking cannot be exchanged online. Contact Jinko support.”, and asking again cannot succeed.
A commit prices its offer again before it starts. If the airline refuses that request (an offer that expired, a leg selection it cannot serve), the commit answers 400 with INVALID_EXCHANGE_REQUEST, INVALID_SEGMENTS_TO_EXCHANGE or PARTIAL_EXCHANGE_UNSUPPORTED, the same three pricing answers. Nothing is exchanged or charged; shop again.
When a Jinko agent has the exchange
An exchange that cannot be completed automatically is handed to a Jinko agent. Its status keeps readingpending, with manual_handling.status: pending beside it. Polling does not move it; the agent completes or fails it, and the status then reads confirmed, failed or partial_failure. A shop the airline does not complete answers support_level: MANUAL_REQUIRED with reason_code: MANUAL_REQUIRED, the fixed reason “This request needs manual handling by Jinko support.”, and no offers. reason is Jinko’s sentence for the customer, never the airline’s wording. That is different from a shop that found no flight, which answers AUTO with no offers.
When an exchange can’t be refunded automatically
A cheaper exchange can need Jinko support to pay the refund, for example when it must be split across payments. Pricing tells the traveler that confirming the exchange sends it to support. Pricing alone does not open a support request or change the ticket. After the traveler confirms, commit the selected exchange. A refusal carryingmanual_handling.status: "pending" means the request is now with Jinko support. Tell the traveler:
This exchange can’t be refunded automatically, so it has been sent to Jinko support. They will complete it and refund you; there is nothing else to do.Do not present this as a completed exchange or ask the traveler to keep retrying. The existing ticket remains in place while support handles the request. The synchronous message is the notice; no separate email is sent when the request opens.
Track the request
Readget_booking for the flight item’s servicing.exchange:
While the request is open, the booking currency’s
servicing_summary has attention_required: true. After completion, the refund is included in the summary’s refunded. The usual exchange confirmation email includes the new itinerary and total refunded. The manual-exchange view is hidden if the item is being cancelled or has been cancelled.
What support does
Jinko support reviews the request, completes the exchange with the airline and refunds the traveler, splitting the refund across the booking’s payments when needed. If support cannot complete it, they close the request with a reason, andservicing.exchange reads failed. You don’t need to call anything while support handles the request.