Fares Per Segment

This guide explains how to integrate and book journeys where different fare classes or products are selected for specific segments of a trip (e.g., traveling in First Class for one leg and Economy for another).

In a standard booking flow for all our carriers, a single fare usually applies to the entire journey. With Fares per Segment, the API allows you to mix and match fares within a single connection. This is common for trips involving different vehicle types or when a traveler wants specific flexibility for only one portion of their journey.

How it Works

The core of this feature is the partial_fares relationship found within the connection object. While standard fares cover all segments of a connection, each fare within partial_fares covers only a specific subset of segments and passengers.

To successfully book a trip using this method, you must select a combination of partial fares that collectively cover all segments and all passengers of the connection exactly once.

Step-by-Step Implementation

1. Find Connections

Perform a standard search using the /connections/find endpoint.

2. Identify Partial Fares

In the search response, look into the relationships of a connection. If the connection supports per-segment fares, you will see a list of offers under partial_fares.

Each partial fare includes:

• segment_ids: The specific segments this fare covers.
• passenger_ids: The specific passengers this fare applies to.
• offer_id: The unique identifier used for booking.

3. Select a Valid Combination

Choose a set of offer_id that cover every segment of the trip for every traveler.

Example Selection Logic

For a 2-segment outbound trip for 1 passenger:

• Select one offer_id from partial_fares for Segment A.
• Select a second offer_id from partial_fares for Segment B.

4. Validate with Vacancy

Before creating a reservation, validate your selection using the /connections/vacancy endpoint. Pass the chosen offer_id in the offers array within the request body.

{
    "locale": "en",
    "currency": "EUR",
    "offers": [
        {
            "id": "cfe63acc-07eb-4463-9a88-b035c935f032|0",
            "passenger_ids": [
                "pax-40-1"
            ]
        },
        {
            "id": "cee51003-5ee5-45bd-8adc-b46dd1c04b88|8",
            "passenger_ids": [
                "pax-40-1"
            ]
        }
    ],
    "passengers": [
        {
            "id": "pax-40-1",
            "type": "PNOS",
            "pax": 1
        }
    ]
}

5. Create and Confirm Reservation

Once vacancy is confirmed, use the same array of offers in your /reservations/create request. Proceed to /reservations/confirm as usual to finalize the booking.

Data Aggregation Rules

When booking mixed fares, the system applies specific rules to determine the final booking attributes:

Price

The total price of the booking is the sum of the prices of all selected partial fares.

Cancellation & Refund Conditions

When segments have different policies, the conditions are concatenated.

• Proportional Refunds: If one segment is refundable and another is not, only the portion of the price paid for the refundable segment can be recovered (minus fees).
• Deadlines: The most restrictive cancellation deadline across all segments applies to the entire booking.

Amendments

The ability to amend a booking is governed by the most restrictive condition across the journey.

• Restrictive Rule: If any one segment is non-amendable, the entire booking is non-amendable.
• Concatenation: Unlike refunds, the binary nature of amendments means one restrictive segment blocks the action for the entire connection.

Tickets

The final ticketing output depends on carrier capabilities and the fare combination.

• Consolidation: You may receive a single consolidated ticket or individual tickets for each segment.
• Compatibility: Single calls to the /bookings/{id}/tickets endpoint will return all necessary documents for the journey regardless of the number of partial fares used.

Fare Features (Amenities)

Amenities are applied per segment based on the specific fare selected for that leg. Travelers only receive benefits (e.g., Wi-Fi, lounge access) associated with the fare class chosen for that specific segment.

Important Considerations

Mandatory Full Coverage

Your selection must cover all segments and all passengers within the connection exactly once.

• Gaps: If any segment is left without an associated offer_id, the request will fail.
• Overlaps: You cannot provide two different offers for the same segment or passenger.

Booking Response Fare Class

When a booking is completed, the final booking response will only display one of the fare classes (usually the most restrictive or primary one). While your individual segment selections are recorded in the background for pricing and amenities, the high-level booking object follows a single-fare class display for compatibility.

No Mixing of Fares and and Partial Fares

You must choose between booking a standard connection-level fare or a per-segment combination. If you provide an offer_id from the global fares array, you cannot include any IDs from the partial_fares relationship.

Our recommodation is to apply these rules:

1. For connections with content under fares only = use fares content
2. For connections with content under partial_fares only = use partial_fares content
3. For connections with content under fares and partial_fares = use partial_fares content

Expiration Synchronization

When selecting multiple partial fares, the earliest expiration time among all selected offers becomes the effective deadline for the entire booking.

Carrier-Specific Combinability

Transport providers determine which fare classes are "combinable." A carrier may reject specific mixed-class pairings during the /vacancy step even if the segments do not overlap. Always rely on the /vacancy endpoint to confirm your specific combination is valid.