Skip to main content
POST
Commit a flight exchange
Execute a previously priced exchange. A commit answers status: "pending"; poll exchange status until it reads confirmed, partial_failure or failed.

When the customer pays the difference

With payment_outcome: "ADD_COLLECT" the commit carries checkout_url, the page where the customer pays the difference. Nothing is exchanged until that payment authorizes. Send the customer to the page, then poll exchange_status, which returns the same checkout_url while the payment is outstanding. The page takes the payment for up to one hour, or until the new fare’s own deadline when that comes sooner. Until then a second commit answers 409 with code: "exchange_in_progress" and starts nothing. If the customer has not paid by then, the exchange is cancelled within a minute: exchange_status answers failed with the reason in warnings and no checkout_url, the page no longer works, nothing is charged and the booking is unchanged. The booking can then be exchanged, refunded or cancelled again; a new commit starts a new exchange with a new checkout_url.

When an exchange can’t be refunded automatically

A 409 with manual_handling.status: "pending" means the confirmed request is with Jinko support, who will complete it and refund the traveler. Show error.message and do not automatically retry commit. Read get_booking and the item’s servicing.exchange to follow the request through manual handling to completion or closure. Pricing alone does not open the request. See Flight exchanges for the customer-visible states and support workflow.

Authorizations

X-API-Key
string
header
required

Body

application/json
offer_id
string
required
Minimum string length: 1
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
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

Commit a flight exchange

airline_locator
string
deprecated

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.

Example:

"ABC123"

booking_ref
string
Example:

"JNK-A0AUR2"

booking_reference
string
deprecated

Deprecated: use booking_ref instead. Same value.

Example:

"JNK-A0AUR2"

new_ticket_numbers
string[]
Example:
status
enum<string>

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.

Available options:
confirmed,
pending,
partial_failure,
failed
Example:

"pending"

payment_outcome
enum<string>

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.

Available options:
EVEN,
ADD_COLLECT,
REFUND
Example:

"ADD_COLLECT"

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.

Example:

"https://app.gojinko.com/checkout?t=eyJyIjoiY2FydCIs…"

stripe_checkout_session_url
string
deprecated

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.