The Offers Flow

The Distribusion API identifies a bookable fare by a persistent offer_id. A search returns an
offer id for each fare it finds; that id is then the only trip context the following calls need.
Vacancy is checked by offer id, and a reservation is created from it — neither call re-sends station
codes, times, carrier codes or fare classes.

This applies to the first three steps of the flow: /connections/find, /connections/vacancy and /reservations/create. Confirmation, retrieval, cancellation and amendment are unaffected and continue to work from the reservation_id and booking_id.

Offer ids also carry the structure that segment-level fares, ancillaries and seat maps depend on, so
anything beyond a single undifferentiated fare per connection is expressed through them.

What an offer is

An offer is one bookable commercial proposition: a specific fare, for specific passengers, over specific segments, at a stated price. Where a connection describes the journey — times, stations, vehicles — an offer describes what it costs and on what terms.

Each offer carries an offer_id, in a format such as 7a9bd0be-e5c8-4995-a259-faf096e78493|0. The id is issued by /connections/find and is the handle for that fare through the rest of the flow. It is distinct from the resource id on the object that contains it.

An offer id is not valid indefinitely. Offers are typically valid for 30 minutes from the search that produced them, and each offer carries an offer_expires_at timestamp which is authoritative — some are issued with a shorter or longer window. Once it has passed, the offer cannot be used for /connections/vacancy or /reservations/create and must be replaced by a fresh search. This is separate from the hold on a reservation, which has its own expires_at and defaults to 10 minutes.

An offer states its own scope rather than leaving it to be inferred. passenger_ids and segment_ids name exactly who and what it covers, and passenger_coverage_type and segment_coverage_type say whether the price applies once across that set or once per member of it.
booking_type says whether the offer stands on its own, needs a counterpart, or is a component of another offer. Because scope is stated, a fare that differs by segment, or an ancillary that applies to one passenger on one leg, is expressible without a separate mechanism.

Working with offer ids

/connections/find and /connections/vacancy accept POST with a JSON body. GET with query parameters is still accepted, but the body form is what the offers flow is documented against and is the recommended method for new integrations.

Locations are given as a single departure_location and arrival_location object, each stating a type and a value, rather than as separate departure_station and departure_city parameters. Trip context is grouped into a search_bounds array, which is what makes multi-bound journeys expressible.

Passengers are assigned ids at search time — pax-40-1 and so on — and those ids are referenced at every following step. This is what ties a fare to a named traveller rather than to a count, and it is what makes a per-passenger price legible when an offer covers several people.

From there the flow is:

1. Search. /connections/find returns offers, each with an offer_id and its own
   fare_conditions.
2. Check price and vacancy. /connections/vacancy takes the selected offer_id, or several for a return, together with the passenger_ids each one applies to. No trip parameters are re-sent.
3. Reserve. /reservations/create takes the verified offer_id in its offers array, and binds traveller data — first_name, last_name, birthdate — to the passenger ids established at search.

For a return journey, the recommended approach is two /connections/find calls: pass the chosen outbound offer_id in the offers array of the inbound search. Carriers that price a return against its outbound — SNCF and Eurostar among them — only surface the discounted inbound fare when the outbound offer is supplied.

After the reservation

Offers end at reservation creation. Everything past that point is keyed on identifiers the offers flow does not touch.

• Confirmation and status. /reservations/confirm and /reservations/{reservation_id} are unchanged and work from the reservation_id.
• Post-booking. Retrieval, ticketing and cancellation are unchanged and work from the
  booking_id. See Identifiers and their lifetime for which of these survive an amendment.
• Ancillaries and seat maps. Both are expressed as offers, with the same offer_id handle and the same coverage fields as a fare. See Ancillaries and Seat Map.

Migrating from the legacy flow

Integrations that predate offers send trip parameters on every call, and are still accepted. The tables below map each legacy call onto its offers equivalent, for anyone moving an existing integration across.

Step 1: Searching for Trips /connections/find

Step 2: Checking Price & Vacancy /connections/vacancy

Step 3: Creating a Reservation /reservations/create