Find available seats
Show travelers the seats available for their flight before payment. Seat offers contain a numberedseat_map for one flight segment. Each seat lists its availability and characteristics, with price_money for a paid seat. Availability depends on the flight, and the traveler can book without selecting seats.
Open the seat map
ReadGET /v1/trip/{trip_id} after adding the flight and travelers. When a seat map is available and the trip can still be changed, the response includes seat_map_url. Open that link to let the traveler pick seats on a seat map. No API key is needed to use the page.
The link expires. Read the trip again for a fresh link. Builder MCP get_trip / trip and the CLI command jinko trip-status show the same link.
Wait for availability
A seat offer initems[].available_ancillaries[] carries seat_map_status beside seat_map:
Example questions
- “Can I choose my seats before paying?”
- “Are seats available on both flights?”
- “Can I book without choosing a seat?”
Choose seats
Help each traveler choose an available seat for each flight segment.Seat map page
Open the Jinko seat map page usingseat_map_url so the traveler can choose seats before payment. Paid seats are priced in the trip currency. Free seats have no price.
Integration selection
Select seats through the API, Builder MCPtrip with select_ancillaries, or CLI jinko select-ancillaries.
To select a seat, send the seat offer’s offer_id, its one segment_ref_ids entry, a seat_number whose available is true, and the traveler’s traveler_ref from the trip response. For example, a selection can identify traveler pax_1, segment ["seg_1"], and seat 12A. Choose one seat per traveler per segment.
Send every ancillary that should remain selected: select_ancillaries replaces the item’s previous selections.
This illustrative trip response shows selected fields. The paid seat costs EUR 15.00; free seats omit the price.
- “Can we sit together, with one window seat?”
- “Which seats have extra legroom?”
- “Change my seat and keep the checked bag I selected.”
Check out
Include the traveler’s current seats in the payment flow. Review the seat choices and prices before creating checkout. See Trips and checkout for the payment flow. Example questions- “How much do these seats add to my trip?”
- “Does this payment include the seats I just chose?”
Manage after booking
Track each seat separately from the flight confirmation. Readbooked_ancillaries for each seat’s status, assigned seat_number, and any failure_reason. Flight confirmation does not guarantee that every selected seat is confirmed.
Confirmation and charges
Jinko sends thebooking.completed event and booking confirmation email once the flight is ticketed, even if a seat is still pending. Check each seat’s outcome in booked_ancillaries.
not_charged: true means this seat is not charged to the traveler. failure_reason explains why the seat is pending or failed. If a failed seat had already been charged, it is refunded.
Example questions
- “My flight is confirmed. Is my seat confirmed too?”
- “Why could the airline not confirm my seat?”
- “What does this seat’s status mean?”
Cancel and refund
If a booking with a charged seat is canceled, the seat is refunded once the airline refunds Jinko. Until then, itsrefund.status reads pending_airline_refund. Show that refund as pending, rather than already returned.
Example questions
- “Was my paid seat refunded too?”
- “Is my seat refund still waiting for the airline?”