New Offers Flow Explained

We recognize that updating your integration takes time, so we designed this guide to ensure a seamless transition. This structural update simplifies your workflow by replacing repetitive parameter passing with a streamlined, persistent "Offer ID" element. This new foundation unblocks advanced features like segment-specific fares and improved ancillary handling and future-proofs your integration.

While we are excited to unlock these capabilities, your operational stability remains our top priority. This update is a fully backwards-compatible extension of the same API version and has been rigorously tested on our own internal frontends. These changes impact the search, vacancy and reservation creation steps, so booking finalization and post-booking endpoints remain entirely unchanged.

Why are we implementing Offers?

We are introducing this new flow to simplify the implementation of the API for your general workflow. The previous API structure relied on an outdated and counter-intuitive method where every request required repeating the same set of parameters (like station codes, times, and carrier codes). This created limitations and blockers to developing new features.

The new flow aligns our API more closely with the industry standard of using persistent IDs. It provides a more flexible fare offering, ensures it is future-proof for upcoming certification requirements, and acts as a foundation for all new functionalities, including updated flows for ancillaries, seat map, and amendments.

How are we doing it?

This update is an extension of our existing API workflow and endpoints. We have intentionally designed this to be backwards compatible. Furthermore, this public release comes only after thorough internal implementation testing on our own frontends and selected partners to ensure stability and reliability.

Key Architectural Changes

• From GET to POST: The recommendation is to switch from the GET method to the POST method for API requests to /connections/find and /connections/vacancy. With POST, all parameters are included in the body of the request, offering a cleaner and more standardized format.
• The Offer ID Paradigm: Your initial search on /connections/find generates a unique offer_id. This persistent ID is then reused for all subsequent requests, eliminating the need to repeat connection parameters.
• Location Parameterization: Parameters are structured differently, using a single departure_location concept instead of separate parameters like departure_station or departure_city.
• Unified Passenger Tracking: Passengers are now assigned unique identifiers (e.g., pax-40-1) early in the search flow. These IDs are referenced across subsequent steps to accurately map distinct traveler details.

Endpoint-by-Endpoint Migration Guide

Step 1: Searching for Trips /connections/find

Step 2: Checking Price & Vacancy /connections/vacancy

Step 3: Creating a Reservation /reservations/create

Next Steps: Confirming the Reservation and Subsequent Steps

While the initial search and reservation creation steps have been significantly streamlined, we have intentionally preserved the stability of your high-risk booking finalization and post-booking workflows.

• Reservation Confirmation & Status: There are no changes to the /reservations/confirm or /reservations/{reservation_id} endpoints. You will continue to use the reservation_id exactly as you do today to ensure backward compatibility and stability.
• Post-Booking Operations: All retrieval and cancellation workflows remain entirely consistent. You will continue to use the booking_id with absolutely no changes required on your end.
• Ancillaries & Seat Maps: Historically, these had complex, carrier-dependent implementations. Moving forward, ancillaries and seat maps will be integrated using a standardized flow.