Working with fare classes

This guide is intended for organizations that have an existing API integration with Betterez, and need to extend their integration to support passenger Fare Classes.

What is a Fare Class?

A Fare Class is a level of service that is offered to passengers. An operator can configure one or more Fare Classes in the system, and passengers can choose which Fare Class they'd like to travel in whenever they make a reservation. The price of the passenger's ticket will vary depending on which Fare Class they choose.

For example, an operator could configure two Fare Classes, named "Economy" and "Premium". The Economy class may have reduced leg room, and does not allow the passenger to cancel their ticket once it has been purchased. The Premium class may have extra leg room and allow ticket cancellations, in exchange for a higher price. Passengers must select one of these two Fare Classes when purchasing a ticket.

Not all Fare Classes will be available for all trips. The API response of GET /inventory-trips/trips will indicate which Fare Classes are available.

When the operator enables Fare Classes for a Product, the response of the GET /inventory-trips/trips endpoint will change. Previously, the endpoint would return pricing information in the array of fares, and the fareClasses property would be set to an empty array:

// Example trip search results when Fare Classes are not enabled

{
  "departures": [
   {
     ...
     "fares": [
        {
         "id": "52f96daea8663b2704000017",
         "name": "Adult",
         "valueToDisplay": "44.00",
         ...
        } 
      ],
      "fareClasses": [],
      ...
    }
  ],
  returns: [...]
}

After enabling Fare Classes, the `fares` array will always be empty, and all pricing information can be found in the `fareClasses` property instead: 
// Example trip search results when Fare Classes are enabled

{
  "departures": [
    {
      ...
      "fares": [],
      "fareClasses": [
        {
          "id": "5ae0afc33268545a78e327f5",
          "name": "Economy",
          "fares": [
            {
             "id": "52f96daea8663b2704000017",
             "name": "Adult",
             "valueToDisplay": "38.00",
             ...
            } 
          ]
        },
        {
          "id": "5c055ebdac3a26ce1c0f1b42",
          "name": "Premium",
          "fares": [
            {
             "id": "52f96daea8663b2704000017",
             "name": "Adult",
             "valueToDisplay": "55.00",
             ...
            } 
          ]
        }
      ],
      ...
    }
  ],
  returns: [...]
}

Note that the passenger's requested fare type ("Adult") appears twice (once in each of the two Fare Classes), and has a different price depending on which Fare Class the passenger selects.

Changes to the user flow

In addition to selecting their desired outbound and return trip, the passenger should also be prompted to select one of the Fare Classes that was returned in the API response for that particular trip. Note that different trips may have a different set of available Fare Classes.

For both the outbound and return trip, your application should remember which Fare Class the passenger selected. The selected Fare Class' id will be required in a subsequent API call.

Changes to the shopping cart

When Fare Classes are in use, the passenger's selected Fare Class IDs must be provided to the POST /sales/cart endpoint. This endpoint is called when the reservations are added to the user's shopping cart:

// Example request body to POST /sales/cart when Fare Classes are enabled

{
    ...
  "items": {
    "reservation": [
      {
        ...
        "passengers": [
          {
            "firstName": "Jane",
            "lastName": "Doe",
            "fare": "Adult",
            "fareId": "52f96daea8663b2704000017",
            ...
            "fareClassIds": {
              "outbound": "5ae0afc33268545a78e327f5",
              "return": "5c055ebdac3a26ce1c0f1b42"
            }
          }
        ]
      }
    ]
  }
}

Note the new `fareClassIds` property above.

After purchasing

The passenger's purchased ticket will display the name of their selected Fare Class.