Skip to main content
POST
Shop for flight exchange alternatives
List the alternative itineraries available to swap a booked flight onto. Pick one and price it with exchange price. Name each leg to change in segments_to_exchange by its first departure and final arrival airport, as get_booking lists it under items[].confirmation.details.flight.legs; legs you do not name stay as booked. preferred_departure_date moves the first leg to that date and reshops every leg, so use it only for a booking with a single leg. A selection the booking refuses answers 400 before any supplier is asked: LEG_ALREADY_DEPARTED, DEPARTURE_DATE_IN_PAST, LEG_DATES_OUT_OF_ORDER or INVALID_SEGMENTS_TO_EXCHANGE. error.message lists the booked legs, except for an INVALID_SEGMENTS_TO_EXCHANGE entry that is malformed (a field of the wrong type, or a date not written YYYY-MM-DD). A booking that cannot be exchanged as it stands answers 409 NOT_EXCHANGEABLE. See Errors.

Authorizations

X-API-Key
string
header
required

Body

application/json
booking_ref
string

Jinko booking reference. Call get_booking first, then select its booked_item_id for servicing.

Minimum string length: 1
Example:

"JNK-A0AUR2"

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.

Pattern: ^itm_[a-z2-7]+$(?![\s\S])
Example:

"itm_aaaaaaaaaaaaafhuxsdxpbzrbfz5hm3a"

last_name
string

Required for guest lookup. A credential that owns the booking may omit it; ownership is checked by the platform.

Minimum string length: 1
Example:

"Doe"

order_id
string
deprecated

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.

Minimum string length: 1
provider
string
deprecated

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
object
segments_to_exchange
object[]

The legs to change. Each entry is matched to a booked leg by its origin and destination and gives the new departure date. Booked legs you do not list are kept unchanged: every offer is the whole itinerary, with the kept legs as booked. Name each leg by its booked airport codes (type: airport): the first departure and the last arrival airport of that journey, as get_booking lists the leg — not a connection airport. A city code cannot be matched and is refused. An entry that matches no booked leg is refused with 400 INVALID_SEGMENTS_TO_EXCHANGE; a leg that has already departed with 400 LEG_ALREADY_DEPARTED; a date before today at the departure airport with 400 DEPARTURE_DATE_IN_PAST; new dates that would put the legs out of order with 400 LEG_DATES_OUT_OF_ORDER. Each refusal lists the booked legs. Some suppliers cannot keep a leg yet; for those bookings a request that names only some of the legs is refused with 400 PARTIAL_EXCHANGE_UNSUPPORTED — name every leg to reshop the whole itinerary.

Minimum array length: 1
preferred_departure_date
string

Legacy. Moves the FIRST leg of the booking to this date and reshops every leg, so it cannot change only a later leg (a return) and can replace the flights of a leg you meant to keep. Use segments_to_exchange instead.

Response

Shop for flight exchange alternatives

support_level
enum<string>

How this action can be carried out. AUTO — the platform completes it end to end through the API. MANUAL_REQUIRED — it is possible, but a Jinko agent has to act; call the API to raise it and expect a delay rather than an immediate result. UNSUPPORTED — the provider or fare does not allow it at all; nothing you send will change that. Do not treat MANUAL_REQUIRED as a failure, and do not retry UNSUPPORTED. On the refund check manual_reason says why it is not AUTO, on the exchange shop reason.

Available options:
AUTO,
MANUAL_REQUIRED,
UNSUPPORTED
reason_code
string

Why the exchange is not automatic, as a Jinko code to route on, never a supplier’s. Present whenever support_level is not AUTO, absent when it is. Today NOT_EXCHANGEABLE with support_level: UNSUPPORTED — the booking cannot be exchanged online — and MANUAL_REQUIRED with support_level: MANUAL_REQUIRED — a Jinko agent has to carry out the exchange.

Example:

"NOT_EXCHANGEABLE"

reason
string

Why the exchange is not automatic, in words the customer can be shown. Present whenever support_level is not AUTO, absent when it is. It is a fixed Jinko sentence and never the supplier’s wording: “This booking cannot be exchanged online. Contact Jinko support.” with NOT_EXCHANGEABLE, “This request needs manual handling by Jinko support.” with MANUAL_REQUIRED.

Example:

"This booking cannot be exchanged online. Contact Jinko support."

offers
object[]
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.