Please make sure you read the Conventions before continuing with this guide.

Requirements.

You will need an X-API-KEY.

Finding trips

You will interact with the /inventory-trips/trips endpoint of the Inventory Bucket to find a trip given some parameters.

Notice the fareIds is not only an array of fareIds, but they include the number of passengers for that fare Id as well. The fareId and the qty are separated by a colon :.

The originId and destinationId parameters are station ids.

The response will contain zero or more departure and return Trips. For each Trip, pricing information can be found in the fares property, or the fareClasses property if you performed a search for a product that has Fare Classes configured.

* Replacement fares

When replaceFaresOnLowAvailability=true is sent and one or more of the requested fares are unavailable (e.g. sold out or past their per-fare capacity limits) but the product's base fare is available, the trip is still returned. The unavailable fares are "replaced" by the base fare so the trip remains bookable — the caller is responsible for detecting the replacement and using the replacement fare's data downstream.

How to detect a replacement

On each trip, inspect every entry in the fares array (or fares inside fareClasses if Journey Pricing is being used) :

• If replacementFareId is null and amountReplaced is 0, the fare was not replaced — treat it as a normal fare.
• If replacementFareId is set, that fare was replaced. The value of replacementFareId matches the id field of an entry in the trip's replacementFares array — look it up there to get the replacement fare's pricing and metadata.
• amountReplaced is the number of passengers of that fare that were swapped to the replacement fare.

Example

Request asked for 1 Adult and 1 Senior. Senior is unavailable but Adult (base) is, so the trip is returned with the Senior replaced by Adult. Trimmed response:

{
  "fares": [
    {
      "id": "60b94ceb1516d01a41ccbbc4",
      "name": "Adult",
      "value": 5000000,
      "valueToDisplay": "50.00",
      "replacementFareId": null,
      "amountReplaced": 0,
      "cancellable": true,
      "changeable": false
    },
    {
      "id": "610aebf7476dc22c1f2d0fee",
      "name": "Senior",
      "value": 4250000,
      "valueToDisplay": "42.50",
      "replacementFareId": "60b94ceb1516d01a41ccbbc4",
      "amountReplaced": 1,
      "cancellable": true,
      "changeable": true
    }
  ],
  "replacementFares": [
    {
      "id": "60b94ceb1516d01a41ccbbc4",
      "name": "Adult",
      "value": 5000000,
      "valueToDisplay": "50.00",
      "cancellable": true,
      "changeable": false
    }
  ]
}

In this response:

• The Adult entry in fares is a normal fare (replacementFareId: null, amountReplaced: 0).
• The Senior entry in fares was replaced: replacementFareId: "60b94ceb1516d01a41ccbbc4" points to the Adult entry in replacementFares, and amountReplaced: 1 means 1 Senior passenger was swapped.

How to use the replacement

Once a replacement is detected, treat the matched replacementFares entry as the effective fare for the replaced passengers. It carries normal fare data (value, valueToDisplay, displayCurrencyValue, cancellable, changeable, lexiconKeys, etc.), so it can be used in the same places a regular fare is used: know how many passengers of the original fare were swapped, and compute the per-passenger delta between the original fare's value and the replacement fare's value when needed (reporting, discount tracking, auditing).

Notes

• Replacement only happens when replaceFaresOnLowAvailability=true is sent, the requested fare is unavailable, and the product's base fare is available. Otherwise the trip is filtered out of the response as usual.
• If no fares were replaced on a given trip, replacementFares will be empty and every entry in fares will have replacementFareId: null and amountReplaced: 0.